xote 7.1.0-beta.2 → 7.1.0-beta.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xote",
-  "version": "7.1.0-beta.2",
+  "version": "7.1.0-beta.3",
   "repository": {
     "url": "https://github.com/brnrdog/xote"
   },
@@ -63,10 +63,13 @@
     "rescript.json",
     "ppx/ppx.ml",
     "ppx/build.sh",
+    "ppx/postinstall.js",
+    "ppx/bin",
     "ppx/README.md",
     "ppx/LICENSE.OCaml"
   ],
   "scripts": {
+    "postinstall": "node ppx/postinstall.js",
     "res:build": "rescript",
     "res:clean": "rescript clean",
     "res:dev": "rescript -w",

package/ppx/README.md

@@ -5,15 +5,18 @@ props-deriving component whose returned JSX is decomposed into **fine-grained
 reactive leaves** — the compile-time counterpart to the runtime
 [`View.tracked`](../src/View.res) helper.
 
-> **Status:** experimental, opt-in. The PPX is exercised in CI and used by the
-> [docs site](../docs-website) itself (the Counter demo), but it is **not part
-> of the published npm package** — consumers who want it build it themselves
-> (see [Opt-in for consumers](#opt-in-for-consumers)). It demonstrates that the
+> **Status:** the standard authoring model. The npm package ships the PPX as a
+> prebuilt binary per platform, selected at install time (see
+> [Distribution](#distribution)), so enabling `@xote.component` is a single
+> `ppx-flags` line with no toolchain requirement. The PPX is exercised in CI
+> and used by the [docs site](../docs-website) itself. It grew out of the
 > [`rescript-signals` #34](https://github.com/brnrdog/rescript-signals/pull/34)
-> auto-tracking idea can target Xote's view layer *and* compile away the
+> auto-tracking idea, targeting Xote's view layer *and* compiling away the
 > wholesale-replacement tradeoff of `View.tracked`. See
 > [`docs/proposals/tracked-blocks.md`](../docs/proposals/tracked-blocks.md) for
-> the full design context (this is "Phase 2, fine-grained variant").
+> the full design context, and
+> [RFC #141](https://github.com/brnrdog/xote/issues/141) for the decision to
+> distribute prebuilt binaries and make this the primary model.
 
 ## What problem it solves
 
@@ -207,41 +210,58 @@ exception**; they keep their original copyright headers. The
 and license text is in [`LICENSE.OCaml`](./LICENSE.OCaml), which ships in the
 npm tarball alongside `ppx.ml`.
 
-## Build
+## Distribution
 
-```sh
-sh build.sh   # produces ./ppx (needs ocamlopt; any recent OCaml, tested 4.14)
-```
+The npm package ships the PPX **prebuilt** for the common platforms, under
+`ppx/bin/`:
 
-Wire it into a project's `rescript.json`:
+| Platform | Binary |
+|---|---|
+| Linux x64 | `ppx-linux-x64.exe` |
+| Linux arm64 | `ppx-linux-arm64.exe` |
+| macOS x64 (Intel) | `ppx-darwin-x64.exe` |
+| macOS arm64 (Apple Silicon) | `ppx-darwin-arm64.exe` |
+| Windows x64 | `ppx-win32-x64.exe` |
+
+The binaries are compiled in CI by
+[`.github/workflows/ppx-binaries.yml`](../.github/workflows/ppx-binaries.yml)
+and injected into the tarball by the release workflow. On install, Xote's
+`postinstall` script ([`postinstall.js`](./postinstall.js)) copies the binary
+matching `process.platform`-`process.arch` to `ppx/ppx` (`ppx/ppx.exe` on
+Windows), which is the path consumers reference:
 
 ```json
-{ "ppx-flags": ["xote-tracked-ppx/ppx"] }
+{ "ppx-flags": ["xote/ppx/ppx"] }
 ```
 
-## Opt-in for consumers
+That one line in your `rescript.json` is the whole setup — no OCaml toolchain
+required. Two edge cases:
 
-The compiled binary is platform-specific and is **not** shipped in the npm
-package, and — deliberately — neither is a `ppx-flags` entry in Xote's own
-published `rescript.json`. That last point matters: a ReScript consumer
-recompiles a dependency's sources during its own build and applies that
-dependency's `ppx-flags`, so a PPX listed in Xote's published config would
-force `ocamlopt` on **every** Xote user. Instead the PPX is strictly opt-in.
+- **Install scripts disabled.** Some package managers skip dependency install
+  scripts (pnpm does by default). Approve them for `xote`
+  (`pnpm approve-builds`) or run `node node_modules/xote/ppx/postinstall.js`
+  once.
+- **Unsupported platform.** If no prebuilt binary matches, the install script
+  falls back to compiling `ppx.ml` from source when `ocamlopt` is on the
+  `PATH`, and otherwise prints instructions without failing the install.
 
-The `ppx.ml` source *is* published, so a consumer who wants `@xote.component`
-can build it from the installed package and reference it from **their own**
-`rescript.json`:
+A `ppx-flags` entry is deliberately **not** in Xote's own published
+`rescript.json`: a ReScript consumer recompiles a dependency's sources during
+its own build and applies that dependency's `ppx-flags`, and Xote's `src/`
+carries no `@xote.component` annotations, so listing the PPX there would make
+every build depend on the binary for no benefit. The annotation applies to
+*your* components, which is why the flag lives in *your* `rescript.json` —
+exactly like the `jsx` configuration you already mirror.
 
-```sh
-npm install xote
-sh node_modules/xote/ppx/build.sh      # needs ocamlopt
-```
+## Build from source
 
-```json
-{ "ppx-flags": ["xote/ppx/ppx"] }
+```sh
+sh build.sh   # produces ./ppx (needs ocamlopt; any recent OCaml, tested 4.14)
 ```
 
-Consumers who don't do this are entirely unaffected.
+`build.sh` also accepts an output path relative to `ppx/`
+(`sh build.sh bin/ppx-linux-x64.exe`), which is how the CI matrix produces
+the prebuilt binaries.
 
 ## In this repo
 
@@ -272,7 +292,7 @@ Or step by step from `example/`:
 sh setup.sh             # link toolchain + Xote from the repo root (idempotent)
 sh ../build.sh          # build the ppx
 npm run build           # compile Demo.res through the ppx
-npm run verify          # jsdom runtime check (60 assertions)
+npm run verify          # jsdom runtime check (71 assertions)
 ```
 
 ## Known limitations (it's a prototype)

package/ppx/build.sh

@@ -1,10 +1,17 @@
 #!/bin/sh
-# Compiles the fine-grained @tracked ppx to a native binary using the system
-# OCaml compiler. ReScript 12 hands a ppx an OCaml 4.06 parsetree; ppx.ml
-# vendors those exact AST types, so the only build dependency is ocamlopt
-# (any recent OCaml works — tested with 4.14).
+# Compiles the fine-grained @xote.component ppx to a native binary using the
+# system OCaml compiler. ReScript 12 hands a ppx an OCaml 4.06 parsetree;
+# ppx.ml vendors those exact AST types, so the only build dependency is
+# ocamlopt (any recent OCaml works — tested with 4.14).
+#
+# Usage: build.sh [output-path]
+#   output-path is relative to this directory and defaults to ./ppx.
+#   CI passes bin/ppx-<platform>-<arch>.exe to produce the prebuilt binaries
+#   shipped in the npm package.
 set -e
 cd "$(dirname "$0")"
-ocamlopt -w -a-31 ppx.ml -o ppx
+out="${1:-ppx}"
+mkdir -p "$(dirname "$out")"
+ocamlopt -w -a-31 ppx.ml -o "$out"
 rm -f ppx.cmi ppx.cmx ppx.o
-echo "built $(pwd)/ppx"
+echo "built $(pwd)/$out"

package/ppx/postinstall.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/*
+ * Selects the prebuilt @xote.component ppx binary for the current platform.
+ *
+ * The npm package ships one native binary per supported platform under
+ * ppx/bin/ (built in CI, see .github/workflows/ppx-binaries.yml). This script
+ * copies the matching one to ppx/ppx (ppx/ppx.exe on Windows), which is the
+ * path consumers reference from their rescript.json:
+ *
+ *   "ppx-flags": ["xote/ppx/ppx"]
+ *
+ * Fallbacks, in order:
+ *   1. No prebuilt binary for this platform, but ocamlopt is available:
+ *      compile from the bundled ppx.ml source (build.sh).
+ *   2. Otherwise: print instructions and exit 0. The install never fails —
+ *      the ppx is only needed by projects that list it in their own
+ *      ppx-flags, and Xote's published library sources compile without it.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ppxDir = __dirname;
+const isWindows = process.platform === 'win32';
+const target = `${process.platform}-${process.arch}`;
+const prebuilt = path.join(ppxDir, 'bin', `ppx-${target}.exe`);
+const dest = path.join(ppxDir, isWindows ? 'ppx.exe' : 'ppx');
+
+function installPrebuilt() {
+  if (!fs.existsSync(prebuilt)) return false;
+  fs.copyFileSync(prebuilt, dest);
+  if (!isWindows) fs.chmodSync(dest, 0o755);
+  console.log(`xote: installed prebuilt ppx binary for ${target}`);
+  return true;
+}
+
+function buildFromSource() {
+  const probe = spawnSync('ocamlopt', ['-version'], { stdio: 'ignore', shell: isWindows });
+  if (probe.error || probe.status !== 0) return false;
+  console.log(`xote: no prebuilt ppx binary for ${target}, compiling from source...`);
+  const build = spawnSync('sh', [path.join(ppxDir, 'build.sh')], { stdio: 'inherit' });
+  return build.status === 0 && fs.existsSync(dest);
+}
+
+if (!installPrebuilt() && !buildFromSource()) {
+  console.warn(
+    [
+      `xote: no ppx binary available for ${target}.`,
+      'The @xote.component annotation needs it; the rest of Xote does not.',
+      'To use it, install an OCaml compiler (ocamlopt) and run:',
+      '  sh node_modules/xote/ppx/build.sh',
+      'Supported prebuilt platforms: linux-x64, linux-arm64, darwin-x64, darwin-arm64, win32-x64.',
+    ].join('\n'),
+  );
+}