Propagate platform/browser_only attrs to generated include struct

When [@react.component] generates an include struct with makeProps
and wrapper make, propagate [@platform ...] and [@browser_only]
attributes from the original binding to the include. This allows
browser_ppx to drop the entire include on non-matching platforms,
fixing the 'Unbound value make' error that occurred when browser_ppx
only dropped the internal make binding but left the wrapper.

Author: davesnx

.opencode/plans/fix-ocaml-jsx-makeprops.md

@@ -0,0 +1,91 @@
+# Fix OCaml syntax JSX expansion generating incorrect `makeProps` calls
+
+## Problem
+
+In OCaml/mlx syntax, the PPX generates an extra `()` before labeled arguments in `makeProps` calls:
+
+```ocaml
+(* BUG: *)    Note_header.makeProps () ~title ~preview ~updated_at ()
+(* CORRECT: *) Note_header.makeProps ~title ~preview ~updated_at ()
+```
+
+Root cause: `strip_final_unit_arg` (line 85-88) only strips `(Nolabel, ())` from the END of the arg list. mlx places `()` at the BEGINNING.
+
+## Changes
+
+### 1. Fix `strip_final_unit_arg` → `strip_unit_args`
+
+**File**: `packages/server-reason-react-ppx/server_reason_react_ppx.ml`
+
+**Lines 85-88** — Change from:
+```ocaml
+let strip_final_unit_arg args =
+  match List.rev args with
+  | (Nolabel, { pexp_desc = Pexp_construct ({ txt = Lident "()"; _ }, None); _ }) :: rest -> List.rev rest
+  | _ -> args
+```
+
+To:
+```ocaml
+let strip_unit_args args =
+  List.filter args ~f:(fun (label, expr) ->
+      match (label, expr.pexp_desc) with
+      | Nolabel, Pexp_construct ({ txt = Lident "()"; _ }, None) -> false
+      | _ -> true)
+```
+
+**Line 108** — Update reference from `strip_final_unit_arg` to `strip_unit_args`:
+```ocaml
+  let non_key_args = strip_unit_args non_key_args in
+```
+
+### 2. Add OCaml-syntax cram test for uppercase JSX calls
+
+Create `packages/server-reason-react-ppx/cram/upper-calls-ocaml.t/` with:
+
+**`input.ml`** — OCaml-syntax JSX with unit before labeled args (mlx style):
+```ocaml
+(* Simulates mlx desugaring: <Upper /> *)
+let upper = (Upper.createElement () [@JSX])
+
+(* Simulates mlx desugaring: <Upper count /> *)
+let upper_prop = (Upper.createElement () ~count [@JSX])
+
+(* Simulates mlx desugaring: <Upper> foo </Upper> *)
+let upper_children_single = fun foo -> (Upper.createElement () ~children:[foo] [@JSX])
+
+(* Simulates mlx desugaring: <Foo.Bar a=1 b="1" /> *)
+let upper_nested_module = (Foo.Bar.createElement () ~a:1 ~b:"1" [@JSX])
+```
+
+**`run.t`** — Cram test verifying correct expansion (no extra `()`):
+```
+  $ ../../standalone.exe --impl input.ml -o output.ml
+  $ ocamlformat --enable-outside-detected-project --impl output.ml
+  <expected output showing makeProps ~arg1 ~arg2 () without extra ()>
+```
+
+### 3. Run tests
+
+```bash
+make build    # Rebuild with the fix
+make test     # All existing tests
+make ppx-test # PPX cram tests specifically
+```
+
+### 4. Promote snapshots if needed
+
+If existing test output changes (it shouldn't), review diffs:
+```bash
+make ppx-test-promote
+```
+
+## Verification
+
+- All existing Reason-syntax cram tests must still pass unchanged
+- New OCaml-syntax test must show `makeProps ~arg ()` (no extra `()`)
+- `make build` must succeed
+
+## Issue 2 (Event target types) — No action needed
+
+The `.mli` already defines `target_like` with proper fields (`value`, `checked`, etc.). The bug report's claim of `< >` doesn't match the current code.

.opencode/plans/simplify-head-resource-management.md

@@ -0,0 +1,56 @@
+# Plan: Simplify Head & Resource Management in ReactServerDOM.ml
+
+## Goal
+Make head management and resource management easier to reason about, without changing behavior.
+
+## Steps
+
+### Step 1: Extract `create_initial_resources`, `create_user_scripts` from render_html (lines 889-987)
+
+Extract three helpers:
+- `create_preload_link href` - single preload `<link>` node (deduplicates the two identical `List.map` blocks)
+- `create_initial_resources ~bootstrap_scripts ~bootstrap_modules` - preload links for bootstrap resources
+- `create_user_scripts ~root_data_payload ?bootstrapScriptContent ?bootstrapScripts ?bootstrapModules ()` - the `user_scripts` list
+
+Then `render_html` calls these instead of building everything inline.
+
+### Step 2: Rename Fiber fields for clarity
+
+| Current | New | Rationale |
+|---------|-----|-----------|
+| `visited_first_lower_case` | `root_tag` | Communicates purpose: tracking root HTML tag |
+| `hoisted_head` | `head_element` | Stores the `<head>` element |
+| `hoisted_head_childrens` | `extra_head_children` | Elements promoted into `<head>` (fixes grammar) |
+| `html_tag_attributes` | `html_attributes` | Simpler |
+
+Also rename the Fiber setter/getter functions to match.
+
+### Step 3: Extract `reconstruct_document` from render_html (lines 989-1011)
+
+Move the post-render HTML document assembly into:
+```ocaml
+let reconstruct_document ~fiber ~root_html ~user_scripts ~skip_root = ...
+```
+
+This is the single place to understand (or modify) how the final document is assembled, including any future head reordering (issue #303).
+
+### Step 4: Introduce `element_role` classification type
+
+Replace the nested if/match cascade in `render_lower_case_element` with an explicit classification:
+
+```ocaml
+type element_role =
+  | Html_root          (* <html> at document root *)
+  | Head_section       (* <head> element *)
+  | Body_section       (* <body> element *)
+  | Hoistable_resource (* async <script>, <link rel=stylesheet precedence=...> *)
+  | Hoistable_meta     (* <title>, <meta>, <link> outside head *)
+  | Regular            (* everything else *)
+
+let classify_element ~fiber ~tag ~attributes = ...
+```
+
+Then `render_lower_case_element` becomes a clean match on this type.
+
+### Verification
+Run `make test` after each step. No behavior changes expected.

AGENTS.md

@@ -0,0 +1,127 @@
+# AGENTS.md
+
+## Project Overview
+
+**server-reason-react** is a native OCaml/Reason implementation of React's server-side rendering (SSR) and React Server Components (RSC). It enables writing React components in Reason that compile to both native (server) and JavaScript (client via Melange).
+
+Used in production at ahrefs.com, app.ahrefs.com, and wordcount.com.
+
+## Language & Build System
+
+- **Primary languages**: Reason (`.re`/`.rei`) and OCaml (`.ml`/`.mli`)
+- **Build system**: [Dune](https://dune.build/) (version 3.9+)
+- **Package manager**: opam (OCaml) + npm (JS tooling)
+- **Compiler**: OCaml 5.4.0 (also supports 4.14.1)
+- **JS compilation**: [Melange](https://melange.re/) (Reason/OCaml to JavaScript)
+- **Formatter**: ocamlformat 0.28.1 (config in `.ocamlformat`, profile=default, margin=120)
+
+## Repository Structure
+
+```
+packages/               # Monorepo — all library packages
+  react/                # Core React module (server-side impl)
+  reactDom/             # ReactDOM: renderToString, renderToStream, RSC
+  server-reason-react-ppx/  # JSX PPX transformer for native
+  browser-ppx/          # PPX to strip browser-only code on server
+  melange.ppx/          # Melange compatibility PPX for native
+  Belt/                 # Belt standard library (native impl)
+  Js/                   # Js module (native impl, Melange compat)
+  Dom/                  # DOM type stubs
+  webapi/               # Web API stubs for native compilation
+  url/                  # URL module (dual native/js implementations)
+  promise/              # Promise module (dual native/js)
+  html/                 # HTML generation utilities
+  fetch/                # Fetch API stub
+  runtime/              # Runtime support module
+  expand-styles-attribute/  # Style attribute expansion PPX
+  esbuild-plugin/       # Esbuild plugin for client component extraction
+  react-server-dom-esbuild/ # React Server DOM esbuild integration
+demo/                   # Demo app (Dream server + client hydration)
+benchmark/              # Performance benchmarks
+documentation/          # odoc documentation source (.mld files)
+arch/                   # Architecture reference (browser/server JS)
+```
+
+## Essential Commands
+
+```bash
+make build              # Build the project (dev profile)
+make build-prod         # Build for production
+make test               # Run all unit tests (dune build @runtest)
+make test-promote       # Update test snapshots
+make format             # Format code with ocamlformat
+make format-check       # Check formatting (used in CI)
+make ppx-test           # Run PPX-specific tests
+make ppx-test-promote   # Promote PPX test snapshots
+make demo-serve         # Build and serve the demo
+make bench              # Run benchmarks
+make init               # Full local setup (switch + deps + npm)
+```
+
+## Testing
+
+Three testing strategies are used:
+
+1. **Alcotest unit tests** — Located in `test/` directories within each package. Run with `make test`.
+2. **Cram tests** (snapshot/golden tests) — Located as `.t` files in `cram/` or `tests/` directories. These test PPX transformations by comparing actual output against expected snapshots. Promote changes with `make test-promote`.
+3. **Inline expect tests** — Some packages use inline tests within source files.
+
+Tests should stay explicit and free of test-only logic. Prefer concrete inputs and direct assertions over conditionals, loops, or helpers that hide the behavior being verified.
+
+When modifying PPX code, always run `make ppx-test` and review snapshot diffs carefully before promoting.
+
+## Key Concepts
+
+### Universal Code
+Code that compiles for both native (server) and JavaScript (client). The project uses `copy_files` in dune to share `.re` files between Melange and native library targets. See `documentation/universal-code.mld`.
+
+### PPX Transformations
+Three PPXes are central to the project:
+- **`server-reason-react-ppx`** — Transforms JSX syntax to native React calls
+- **`browser-ppx`** — Strips browser-only code on server (`let%browser_only`, `switch%platform`, `@platform`)
+- **`melange.ppx`** — Makes Melange attributes (`mel.*`, `##`, `[%re]`, etc.) work in native
+
+### Dual Implementations
+Some modules have separate native and JS implementations sharing the same interface:
+- `packages/url/native/` vs `packages/url/js/`
+- `packages/promise/native/` vs `packages/promise/js/`
+
+### React Server Components (Experimental)
+RSC support includes `ReactServerDOM`, an esbuild plugin for client component extraction, and Dream middleware. This is still work in progress.
+
+## Coding Conventions
+
+- Reason (`.re`) is preferred for React components and new application code
+- OCaml (`.ml`) is used for library internals, PPX implementations, and Belt/Js modules
+- Interface files (`.mli`/`.rei`) are used to define public APIs
+- Each package has its own `dune` file defining libraries and test targets
+- Follow existing formatting — run `make format` before committing
+- PPX transformations use `ppxlib` and follow its visitor pattern
+
+## OCaml
+
+- Do not use `Obj.magic` or `%identity` unless it is absolutely necessary.
+- Avoid both at all costs; prefer type-safe alternatives even if they require a slightly larger refactor.
+- If either appears to be the only viable option, stop and ask the user before introducing it.
+
+## Do NOT
+
+- Modify `_build/`, `_opam/`, or `node_modules/` directories
+- Change `.ocamlformat` settings without discussion
+- Skip running tests after modifying PPX code — PPX changes can silently break downstream code
+- Introduce new opam dependencies without updating `dune-project`
+- Assume browser APIs are available on the server — use `let%browser_only` or `switch%platform`
+
+## CI
+
+GitHub Actions (`.github/workflows/ci.yml`) runs on push to `main` and PRs:
+- Matrix: `{macos, ubuntu}` x `{OCaml 4.14.1, OCaml 5.4.0}`
+- Steps: build, format check (OCaml 5+ only), tests, docs generation, benchmarks
+
+## Useful Links
+
+- [Documentation](https://ml-in-barcelona.github.io/server-reason-react/server-reason-react/index.html)
+- [Reason syntax docs](https://reasonml.github.io/docs/en/what-and-why)
+- [Melange docs](https://melange.re/)
+- [Dune docs](https://dune.readthedocs.io/)
+- [ppxlib docs](https://ocaml.org/p/ppxlib/latest/doc/index.html)

Makefile

@@ -103,7 +103,7 @@ demo-serve: demo-build ## Serve the demo executable
 
 .PHONY: demo-serve-watch
 demo-serve-watch: ## Run demo executable on watch mode (listening to built_at.txt changes)
-	@watchexec --no-vcs-ignore -w demo/.running/built_at.txt -r -c -- "_build/default/demo/server/server.exe"
+	@watchexec --no-vcs-ignore -w demo/.running/built_at.txt -r -c -- "DEMO_ENV=development _build/default/demo/server/server.exe"
 
 .PHONY: subst
 subst: ## Run dune substitute

demo/client/DummyRouterRSC.re

@@ -27,15 +27,14 @@ let callServer = (path: string, args) => {
     });
   ReactServerDOMEsbuild.encodeReply(args)
   |> Js.Promise.then_(body => {
-       let body = Fetch.BodyInit.make(body);
        Fetch.fetchWithInit(
          "/",
          Fetch.RequestInit.make(~method_=Fetch.Post, ~headers, ~body, ()),
        )
        |> Js.Promise.then_(result => {
             let body = Fetch.Response.body(result);
             ReactServerDOMEsbuild.createFromReadableStream(body);
-          });
+          })
      });
 };
 

demo/client/NestedRouterRSC.re

@@ -13,15 +13,14 @@ let callServer = (path: string, args) => {
     });
   ReactServerDOMEsbuild.encodeReply(args)
   |> Js.Promise.then_(body => {
-       let body = Fetch.BodyInit.make(body);
        Fetch.fetchWithInit(
          "/",
          Fetch.RequestInit.make(~method_=Fetch.Post, ~headers, ~body, ()),
        )
        |> Js.Promise.then_(result => {
             let body = Fetch.Response.body(result);
             ReactServerDOMEsbuild.createFromReadableStream(body);
-          });
+          })
      });
 };
 

demo/client/SinglePageRSC.re

@@ -6,15 +6,14 @@ let callServer = (path: string, args) => {
     });
   ReactServerDOMEsbuild.encodeReply(args)
   |> Js.Promise.then_(body => {
-       let body = Fetch.BodyInit.make(body);
        Fetch.fetchWithInit(
          "/",
          Fetch.RequestInit.make(~method_=Fetch.Post, ~headers, ~body, ()),
        )
        |> Js.Promise.then_(result => {
             let body = Fetch.Response.body(result);
             ReactServerDOMEsbuild.createFromReadableStream(body);
-          });
+          })
      });
 };
 

demo/dream-nested-router/js/HistoryState.re

@@ -1,27 +1,30 @@
 module DOM = Webapi.Dom;
-module History = DOM.History;
 
-/**
- * Melange webapi don't set state type, so we use Obj.magic to cast it to the correct type while the PR is not merged.
- * https://github.com/melange-community/melange-webapi/blob/80c6ededd06cc66b75445d1ed5c855e050b156a0/src/Webapi/Dom/Webapi__Dom__History.re#L2
- * PR: https://github.com/melange-community/melange-webapi/pull/29
- */
-[@platform js]
-type t = History.state;
+/* Custom History bindings with polymorphic state, replacing the upstream opaque type from melange-webapi. Also waiting for the PR to be merged: https://github.com/melange-community/melange-webapi/pull/29 */
+module History = {
+  type t = Dom.history;
+
+  [@mel.get] external state: t => 'a = "state";
+
+  [@mel.send]
+  external pushState: ([@mel.this] t, 'a, string, string) => unit =
+    "pushState";
+
+  [@mel.send]
+  external replaceState: ([@mel.this] t, 'a, string, string) => unit =
+    "replaceState";
+};
 
 let fromEvent = event =>
   DOM.Event.target(event)
   ->DOM.EventTarget.unsafeAsWindow
   ->DOM.Window.history
   ->History.state;
 
-let toJs: History.state => Js.t({..}) = state => state |> Obj.magic;
-let fromJs: Js.t({..}) => History.state = state => state |> Obj.magic;
-
 [@platform js]
 let push = (state, path) => {
-  History.pushState(state, "", path, DOM.history);
-  let _ =
+  History.pushState(DOM.history, state, "", path);
+  let (_: bool) =
     DOM.EventTarget.dispatchEvent(
       DOM.Event.make("popstate"),
       DOM.Window.asEventTarget(DOM.window),
@@ -31,8 +34,8 @@ let push = (state, path) => {
 
 [@platform js]
 let replace = (state, path) => {
-  History.replaceState(state, "", path, DOM.history);
-  let _ =
+  History.replaceState(DOM.history, state, "", path);
+  let (_: bool) =
     DOM.EventTarget.dispatchEvent(
       DOM.Event.make("popstate"),
       DOM.Window.asEventTarget(DOM.window),