@windowkit/appkit 0.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (C) 2026 by Andrey Sidorov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,192 @@
+# @windowkit/appkit
+
+A **retained-mode AppKit backend for Node.js**: Core Animation (CALayer)
+layer trees, CoreText layout and drawing, IOSurface presentation, NSMenu and
+native control bezels. It is the macOS half of [react-x11][react-x11].
+Instead of immediate-mode draw calls, you build a persistent tree of layers, mutate their
+properties, and let the macOS WindowServer composite on the GPU — with implicit animations
+and correct retina handling for free.
+
+Built as a drawing-backend experiment for [react-x11]-style reconcilers: React elements map
+1:1 to layers, and `commitUpdate` becomes `layer.set(props)`.
+
+```bash
+npm install   # builds the native addon (macOS only, needs Xcode CLT)
+npm run demo  # hover/click the cards; press "q" to quit
+```
+
+## What the demo shows
+
+- **CALayer tree** — frame/bounds/position, backgroundColor, cornerRadius, borderWidth,
+  shadows, opacity, zPosition, `masksToBounds` clipping
+- **Implicit animations** — hover/click a card: plain `layer.set({...})` property changes
+  animate at 0.25s automatically
+- **CATransaction** — the orange ball tweens over 1.1s with easeInEaseOut just by grouping
+  a `position` change in a transaction
+- **Explicit CABasicAnimation** — the spinner runs two infinite animations
+  (`transform.rotation.z` + `strokeEnd`) entirely in the render server; they stay smooth
+  even if the JS thread stalls
+- **CATextLayer** — retina-crisp text composited by the WindowServer
+- **CoreText** — glyphs measured (`CTLine`) and rasterized (`CTFramesetter` → `CGImage`)
+  then set as `layer.contents`, i.e. the glyph-atlas path
+- **CAGradientLayer + layer.mask** — the footer is a gradient masked by a text layer
+- **CAShapeLayer** — CGPath commands, stroke/fill, dash patterns, animatable `strokeEnd`
+- **Hit testing** — native `-[CALayer hitTest:]` mapped back to JS wrapper objects
+- **Events** — mouse/keyboard from the NSApp event pump delivered to a JS callback
+- **Native controls** — push buttons (incl. accent-filled default), checkboxes, radios,
+  popup buttons, sliders, and switches rendered by AppKit itself and composited as layer
+  contents; fully interactive (pressed states, toggles, slider drag) and re-renderable in
+  dark/light appearance (the "Light / Dark" button flips all of them live)
+
+## How it runs
+
+Node's main thread *is* the process main thread on macOS, so the addon owns
+`NSApplication` directly. Nobody calls `[NSApp run]`; instead JS drives an event pump
+(`nextEventMatchingMask:` with `distantPast`) off a `setInterval`. Core Animation
+animations execute in the render server, so their smoothness is independent of the pump
+cadence — the JS timer only affects input latency.
+
+The window uses a **layer-hosting** `NSView` (we own the whole CALayer tree) with
+`isFlipped = YES`, which makes AppKit give the hosted layer a top-left origin
+(`geometryFlipped`) — coordinates match what a UI toolkit expects. Two flip gotchas are
+handled in native code: `hitTest:` still takes bottom-up points, and
+`renderInContext:` ignores `geometryFlipped` entirely (snapshots therefore capture the
+window's real composited pixels via `CGWindowListCreateImage`, which needs no
+screen-recording permission for the process's own windows).
+
+## API sketch
+
+```js
+const ca = require('@windowkit/appkit');
+const { app, Window, Layer, TextLayer, GradientLayer, ShapeLayer,
+        transaction, withoutAnimations } = ca;
+
+const win = new Window({ width: 800, height: 560, title: 'hi' });
+
+const card = new Layer();
+card.set({
+  frame: [32, 108, 228, 128],           // top-left origin, points (not pixels)
+  backgroundColor: [0.98, 0.42, 0.36, 1],
+  cornerRadius: 14,
+  shadowOpacity: 0.5, shadowRadius: 12, shadowOffset: [0, 6],
+});
+win.root.add(card);
+
+// implicit animation: just set the property
+card.set({ backgroundColor: [0.36, 0.65, 0.98, 1] });
+
+// batched, with custom duration/curve
+transaction(() => card.set({ position: [400, 300] }),
+            { duration: 1.1, timing: 'easeInEaseOut' });
+
+// no animation (e.g. initial tree construction, reconciler commits)
+withoutAnimations(() => card.set({ opacity: 0.5 }));
+
+// explicit animation on any animatable keyPath
+card.animate('transform.rotation.z',
+             { from: 0, to: Math.PI * 2, duration: 1, repeat: Infinity, timing: 'linear' });
+
+// text, two ways
+const label = new TextLayer();
+label.set({ frame: [0, 14, 228, 22], contentsScale: win.scale })
+     .text({ string: 'hello', fontName: 'HelveticaNeue', fontSize: 15,
+             color: [1, 1, 1, 1], align: 'center' });
+card.add(label);
+
+const glyphs = ca.text.render({ text: 'CoreText', fontName: 'Menlo',
+                                fontSize: 13, color: [1, 1, 1, 1], scale: win.scale });
+new Layer().set({ frame: [10, 10, glyphs.width, glyphs.height] }).setImage(glyphs);
+ca.text.measure({ text: 'CoreText', fontName: 'Menlo', fontSize: 13 });
+// -> { width, ascent, descent, leading }
+
+// masks, gradients, shapes
+const g = new GradientLayer();
+g.gradient({ colors: [[1, 0, 0, 1], [0, 0, 1, 1]], startPoint: [0, 0.5], endPoint: [1, 0.5] });
+g.set({ mask: someTextLayer });
+
+const shape = new ShapeLayer();
+shape.shape({ path: [['move', 0, 0], ['line', 50, 80], ['arc', 25, 25, 20, 0, Math.PI, false]],
+              strokeColor: [1, 1, 1, 1], lineWidth: 4, lineCap: 'round', fillColor: null });
+
+// input + hit testing
+app.onEvent((ev) => {          // mousedown/up/move/drag, wheel, keydown/up
+  const layer = win.hitTest(ev.x, ev.y);   // deepest Layer wrapper or null
+});
+
+app.run({ onTick: () => { if (!win.visible) process.exit(0); } });
+
+win.snapshot('/tmp/out.png'); // real composited pixels of the window
+```
+
+## Native controls
+
+There is no WindowServer API for control drawing — AppKit draws controls in-process via
+the **NSCell** architecture, and cells happily draw offscreen (the technique WebKit's
+`RenderThemeMac` and Firefox's `nsNativeThemeCocoa` use for native form controls).
+`ca.controls.render()` rasterizes a cell at retina scale under a chosen `NSAppearance`
+and returns a `CGImage` for `layer.contents`:
+
+```js
+const img = ca.controls.render({
+  kind: 'push',            // 'push' | 'checkbox' | 'radio' | 'popup' | 'slider' | 'switch'
+  title: 'Click me',
+  pressed: false,          // drive this from your own mouse events
+  state: 1,                // on/off for checkbox/radio/switch
+  isDefault: true,         // push: accent-filled default button
+  value: 0.5,              // slider position
+  controlSize: 'regular',  // 'mini' | 'small' | 'regular' | 'large'
+  appearance: 'dark',      // 'system' | 'dark' | 'light'
+  scale: win.scale,
+});                        // -> { image, width, height, scale } (natural cellSize if
+                           //    width/height omitted)
+new Layer().set({ frame: [x, y, img.width, img.height] }).setImage(img);
+```
+
+Two render paths inside `drawControl`:
+
+- **Cell path** (`NSButtonCell`, `NSPopUpButtonCell`): `drawWithFrame:inView:` into a
+  bitmap `NSGraphicsContext`, wrapped in `performAsCurrentDrawingAppearance:` so dark
+  mode and the user's accent color apply.
+- **Offscreen-view path** (`NSSlider`, `NSSwitch`): modern `NSSliderCell` no longer
+  draws offscreen (it defers to the view's layer machinery), and `NSSwitch` has no cell
+  at all, so these render a real unparented `NSControl` via
+  `displayRectIgnoringOpacity:inContext:`.
+
+The demo re-renders a control's image on each state change; a real renderer would cache
+per `(kind, size, state, appearance)` and nine-slice-stretch bezels with
+`layer.contentsCenter`. Menus/popovers are deliberately *not* painted — their
+vibrancy materials need private API to reproduce; expose real `NSMenu` instead.
+
+`native.postMouseEvent(win, 'down'|'up'|'move'|'drag', x, y)` synthesizes events through
+the real pump — used by the demo's self-test (`CAL_CLICKS="x,y;x,y" npm run demo`).
+
+## Mapping to a React reconciler
+
+The shape of a host config on top of this:
+
+| Reconciler op        | @windowkit/appkit                                        |
+| -------------------- | -------------------------------------------------------- |
+| `createInstance`     | `new Layer()` / `new TextLayer()` / ... per element type |
+| `appendChild`        | `parent.add(child)`                                      |
+| `removeChild`        | `child.remove()`                                         |
+| `commitUpdate`       | `layer.set(diffedProps)`                                 |
+| commit batch         | wrap in `withoutAnimations()` (or a `transaction()` to get animated updates for free) |
+| `getPublicInstance`  | the `Layer` wrapper (hit-testing gives it back for events) |
+
+Because the tree is retained and properties are mutable, the reconciler diff maps directly
+onto layer mutations — no repaint pass, no damage rects; the WindowServer recomposites
+only what changed.
+
+## Caveats (POC)
+
+- The pump-on-a-timer model means live window resizing/dragging runs AppKit's internal
+  modal loops; input during those is choppy (Core Animation itself is unaffected).
+- No `NSWindowDelegate` wiring yet — window resize is observable only by polling
+  `win.size`; sublayers don't autolayout (by design — the reconciler owns layout).
+- One shared event callback for all windows; per-window routing would need the window
+  handle in the event payload.
+- Layer handles are released on GC via External finalizers; native side keeps its own
+  retains through the layer tree, so lifetime is safe but not tuned.
+- `x64`/`arm64` follows whatever node arch you build with; no prebuilds.
+
+[react-x11]: https://github.com/sidorares/react-x11

package/binding.gyp

@@ -0,0 +1,27 @@
+{
+  "targets": [
+    {
+      "target_name": "calayers",
+      "sources": ["src/addon.mm", "src/backend.mm"],
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")"
+      ],
+      "defines": ["NAPI_DISABLE_CPP_EXCEPTIONS"],
+      "xcode_settings": {
+        "OTHER_CPLUSPLUSFLAGS": ["-fobjc-arc", "-std=c++17"],
+        "MACOSX_DEPLOYMENT_TARGET": "11.0",
+        "CLANG_ENABLE_OBJC_ARC": "YES"
+      },
+      "link_settings": {
+        "libraries": [
+          "-framework Cocoa",
+          "-framework QuartzCore",
+          "-framework CoreText",
+          "-framework CoreGraphics",
+          "-framework ImageIO",
+          "-framework IOSurface"
+        ]
+      }
+    }
+  ]
+}

package/index.js

@@ -0,0 +1,184 @@
+'use strict';
+
+if (process.platform !== 'darwin') {
+  throw new Error('@windowkit/appkit is macOS-only (Core Animation backend)');
+}
+
+const fs = require('fs');
+const path = require('path');
+
+// A local build wins (dev iteration), then the prebuilt binary bundled in
+// the npm tarball for this platform/arch (see scripts/install.js — the
+// package works even when install scripts are disabled), then a clear error.
+function loadNative() {
+  const candidates = [
+    'build/Release/calayers.node',
+    'build/Debug/calayers.node',
+    `prebuilds/${process.platform}-${process.arch}/calayers.node`,
+  ];
+  const errors = [];
+  for (const rel of candidates) {
+    const abs = path.join(__dirname, rel);
+    if (!fs.existsSync(abs)) continue;
+    try {
+      return require(abs);
+    } catch (e) {
+      errors.push(`  ${rel}: ${e.message}`);
+    }
+  }
+  throw new Error(
+    `@windowkit/appkit: no loadable native binary for ${process.platform}-${process.arch}\n` +
+      (errors.length ? `tried:\n${errors.join('\n')}\n` : '') +
+      'rebuild with: npm rebuild @windowkit/appkit --build-from-source (needs the Xcode command-line tools)',
+  );
+}
+
+const native = loadNative();
+
+// name -> wrapper, so native hitTest results map back to JS objects
+const layersByName = new Map();
+let seq = 0;
+
+class Layer {
+  constructor(handle) {
+    this._h = handle || native.createLayer();
+    this._name = 'layer:' + ++seq;
+    native.setLayerProps(this._h, { name: this._name });
+    layersByName.set(this._name, this);
+    this.parent = null;
+    this.children = [];
+  }
+
+  // Retained-mode property update. Changes to position/bounds/backgroundColor/
+  // opacity/cornerRadius/transform/... on layers already in a tree get implicit
+  // 0.25s animations from Core Animation unless wrapped in withoutAnimations().
+  set(props) {
+    if (props.mask instanceof Layer) props = { ...props, mask: props.mask._h };
+    native.setLayerProps(this._h, props);
+    return this;
+  }
+
+  add(child) {
+    native.addSublayer(this._h, child._h);
+    child.parent = this;
+    this.children.push(child);
+    return child;
+  }
+
+  remove() {
+    native.removeFromSuperlayer(this._h);
+    if (this.parent) {
+      const i = this.parent.children.indexOf(this);
+      if (i >= 0) this.parent.children.splice(i, 1);
+      this.parent = null;
+    }
+  }
+
+  // Explicit CABasicAnimation on any animatable keyPath, e.g.
+  // 'transform.rotation.z', 'position', 'opacity', 'strokeEnd', 'backgroundColor'.
+  animate(keyPath, opts = {}, key = keyPath) {
+    native.addAnimation(this._h, keyPath, opts, key);
+    return this;
+  }
+
+  removeAnimation(key) { native.removeAnimation(this._h, key); }
+  removeAllAnimations() { native.removeAllAnimations(this._h); }
+
+  // img is the result of text.render() (or any {image, scale})
+  setImage(img, scale) {
+    native.setContentsImage(this._h, img.image, scale ?? img.scale);
+    return this;
+  }
+}
+
+class TextLayer extends Layer {
+  constructor() { super(native.createTextLayer()); }
+  // {string, fontName, fontSize, color, align, wrapped, truncation}
+  text(props) { native.setTextProps(this._h, props); return this; }
+}
+
+class GradientLayer extends Layer {
+  constructor() { super(native.createGradientLayer()); }
+  // {colors: [[r,g,b,a],...], locations, startPoint, endPoint, type}
+  gradient(props) { native.setGradientProps(this._h, props); return this; }
+}
+
+class ShapeLayer extends Layer {
+  constructor() { super(native.createShapeLayer()); }
+  // {path: [['move',x,y],['line',x,y],['arc',cx,cy,r,a0,a1,cw],...],
+  //  fillColor, strokeColor, lineWidth, strokeStart, strokeEnd, lineCap, ...}
+  shape(props) { native.setShapeProps(this._h, props); return this; }
+}
+
+class Window {
+  constructor({ width = 640, height = 480, title = '' } = {}) {
+    native.initApp();
+    this._h = native.createWindow(width, height, title);
+    this.root = new Layer(native.windowRootLayer(this._h));
+    this.scale = native.windowScale(this._h); // backing scale (2 on retina)
+  }
+  get size() {
+    const s = native.windowContentSize(this._h);
+    return { width: s[0], height: s[1] };
+  }
+  get visible() { return native.windowIsVisible(this._h); }
+  hitTest(x, y) {
+    const name = native.hitTest(this.root._h, x, y);
+    return (name && layersByName.get(name)) || null;
+  }
+  close() { native.closeWindow(this._h); }
+  snapshot(file) { return native.snapshotWindow(this._h, file); } // renderInContext -> PNG
+}
+
+// Group property changes into one CATransaction (shared animation duration/timing).
+function transaction(fn, opts = {}) {
+  native.txBegin(opts);
+  try { fn(); } finally { native.txCommit(); }
+}
+
+// Suppress implicit animations for this batch of changes.
+function withoutAnimations(fn) {
+  transaction(fn, { disableActions: true });
+}
+
+let timer = null;
+const app = {
+  onEvent(fn) { native.setEventCallback(fn); },
+  // Drives the NSApplication event pump off node's event loop. Core Animation
+  // itself animates in the render server, independent of this cadence.
+  run({ fps = 60, onTick } = {}) {
+    if (timer) return;
+    native.initApp();
+    timer = setInterval(() => {
+      native.pump();
+      if (onTick) onTick();
+    }, Math.max(4, Math.floor(1000 / fps)));
+  },
+  stop() {
+    if (timer) { clearInterval(timer); timer = null; }
+  },
+  pump: () => native.pump(),
+};
+
+const text = {
+  // CoreText-rendered glyphs -> CGImage, for glyph-atlas style text.
+  // {text, fontName, fontSize, color, maxWidth, scale} -> {image, width, height, scale}
+  render: (opts) => native.createTextImage(opts),
+  // {text, fontName, fontSize} -> {width, ascent, descent, leading}
+  measure: (opts) => native.measureText(opts),
+};
+
+const controls = {
+  // Native control bezels via offscreen NSCell drawing (WebKit/Firefox technique).
+  // {kind: 'push'|'checkbox'|'radio'|'popup'|'slider', title, state, pressed,
+  //  enabled, isDefault, value, controlSize, appearance: 'system'|'dark'|'light',
+  //  width, height, scale} -> {image, width, height, scale}
+  // width/height default to the cell's natural size (sliders must pass them).
+  render: (opts) => native.drawControl(opts),
+  isDark: () => native.appearanceIsDark(),
+};
+
+module.exports = {
+  app, Window, Layer, TextLayer, GradientLayer, ShapeLayer,
+  transaction, withoutAnimations, text, controls, native,
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@windowkit/appkit",
+  "version": "0.1.0",
+  "description": "Retained-mode AppKit backend for Node.js: Core Animation (CALayer) layer trees, CoreText layout and drawing, IOSurface presentation, NSMenu, and native control bezels — the macOS half of react-x11.",
+  "author": "Andrey Sidorov <andrey.sidorov@gmail.com>",
+  "license": "MIT",
+  "main": "index.js",
+  "homepage": "https://github.com/windowkit/appkit",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/windowkit/appkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/windowkit/appkit/issues"
+  },
+  "keywords": [
+    "macos",
+    "appkit",
+    "core-animation",
+    "calayer",
+    "coretext",
+    "iosurface",
+    "nsmenu",
+    "native-controls",
+    "react-x11",
+    "windowkit"
+  ],
+  "os": [
+    "darwin"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "LICENSE",
+    "index.js",
+    "binding.gyp",
+    "src/",
+    "scripts/",
+    "prebuilds/"
+  ],
+  "scripts": {
+    "install": "node scripts/install.js",
+    "build": "node-gyp rebuild",
+    "demo": "node demo/demo.js"
+  },
+  "dependencies": {
+    "node-addon-api": "^8.3.0"
+  },
+  "devDependencies": {
+    "node-gyp": "^11.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gypfile": true
+}

package/scripts/install.js

@@ -0,0 +1,54 @@
+// Install-time dispatch: use the bundled prebuilt binary when one matches
+// this platform/arch and actually loads; otherwise compile with node-gyp.
+// A Mac with no Xcode command-line tools therefore installs from the
+// tarball alone. Force a source build with: npm install --build-from-source
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+// darwin-only package (AppKit / Core Animation). On any other platform the
+// package is inert; there is nothing to build, and `os` in package.json
+// already warns npm — do not fail the install of a cross-platform consumer.
+if (process.platform !== 'darwin') {
+  console.log('@windowkit/appkit: not macOS — skipping native build');
+  process.exit(0);
+}
+
+const root = path.join(__dirname, '..');
+const target = `${process.platform}-${process.arch}`;
+const prebuilt = path.join(root, 'prebuilds', target, 'calayers.node');
+
+if (
+  process.env.npm_config_build_from_source !== 'true' &&
+  fs.existsSync(prebuilt)
+) {
+  try {
+    require(prebuilt); // loading registers exports and touches nothing else
+    console.log(`@windowkit/appkit: using bundled prebuilt binary (${target})`);
+    process.exit(0);
+  } catch (e) {
+    console.warn(
+      `@windowkit/appkit: bundled prebuild did not load (${e.message}); compiling instead`,
+    );
+  }
+}
+
+// npm points npm_config_node_gyp at its own copy; fall back to PATH
+const gyp = process.env.npm_config_node_gyp;
+const result = gyp
+  ? spawnSync(process.execPath, [gyp, 'rebuild'], { cwd: root, stdio: 'inherit' })
+  : spawnSync('node-gyp', ['rebuild'], { cwd: root, stdio: 'inherit' });
+if (result.error) {
+  console.error(
+    `@windowkit/appkit: could not run node-gyp (${result.error.message})`,
+  );
+  console.error(
+    '@windowkit/appkit: no prebuilt binary matches this system and no ' +
+      'toolchain is available. Install the Xcode command-line tools ' +
+      '(xcode-select --install) and reinstall.',
+  );
+  process.exit(1);
+}
+process.exit(result.status === null ? 1 : result.status);