@reventlessdev/reventless-ui-slots 3.0.0-alpha.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2018-2026 Martin Lorenz
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,163 @@
+# `@reventlessdev/reventless-ui-slots`
+
+Types and one runtime helper for writing custom renderers into the regions of
+Reventless AutoUI's standard view modes.
+
+**Write your renderers in JavaScript, TypeScript or ReScript — whichever you
+prefer.** All three produce the same module and the shell cannot tell them apart.
+This package declares the one contract twice: `index.d.ts` for JS and TS,
+`ReventlessSlots.resi` for ReScript. A conformance test in the kit checks both
+against the payloads the shell actually builds, so the two declarations cannot
+drift apart behind your back.
+
+It publishes public. `@reventlesslab/reventless-ui` publishes restricted, so
+without this package writing *any* custom renderer against these seams would need
+a private token — and "custom rendering is supported" would not be a claim an
+open-source user could act on.
+
+## What a slot is
+
+A named region **inside** one of AutoUI's standard view modes. The mode keeps
+everything it owns — paging, the window sentence, the action offers, the drill
+target, the live-update path — and your renderer replaces what is drawn inside
+the region. Every slot is optional and a missing one is not an error: the mode
+draws its own rendering, which is what every deployment already sees.
+
+The alternative, before slots, was writing a whole view mode — which meant owning
+all of the above, every bit of which the mode you were happy with already had
+right.
+
+## Writing one
+
+A slot module is an ES module with one export. No bundler, no dependency, no
+build step: `h` and the registry arrive as arguments.
+
+```js
+export function register({ h, slots }) {
+  slots.row('gallery.tile', ({ row, image, open }) =>
+    h('button', { className: 'tile', onClick: open },
+      h('img', { src: image?.src, alt: image?.alt ?? '' }),
+      h('span', { className: 'tile-name' }, row.name)))
+
+  slots.view('gallery.empty', () =>
+    h('p', { className: 'nothing-yet' }, 'Nothing in this collection yet.'))
+}
+```
+
+Serve that file anywhere the shell's origin policy admits, and point the
+deployment's `config.json` at it:
+
+```json
+{ "uiSlotsUrl": "/slots/shop.js" }
+```
+
+The shell fetches it before the first page renders. A 404, a module with no
+`register`, or a `register` that throws is logged once and skipped — a storefront
+that fails to load degrades to the generated console, visibly, not to a white
+page.
+
+With this package installed, `defineSlots` type-checks the export without
+changing it:
+
+```js
+import { defineSlots } from '@reventlessdev/reventless-ui-slots'
+
+export const register = defineSlots(({ h, slots }) => { /* … */ })
+```
+
+## In ReScript
+
+Add the package to the `dependencies` array in your `rescript.json` — the
+compiler's own dependency list, not the one in `package.json`, though it needs to
+be in both — and write the same module. Compiled with
+`"module": "esmodule"` and an `.mjs` suffix, the output *is* the module the shell
+loads — there is nothing to wrap. Unlike the JS path it needs a bundling step,
+because the compiler emits bare-specifier imports (`@rescript/runtime`, this
+package) that a browser will not resolve from a served file; bundle it with
+esbuild or Vite and serve the one file.
+
+```rescript
+let register = (arg: ReventlessSlots.registerArg) => {
+  arg.slots.row(ReventlessSlots.RowSlot.galleryTile, p =>
+    ReventlessSlots.h(arg.h, "button", {"className": "tile", "onClick": p.openRow}, [
+      ReventlessSlots.h(arg.h, "img", {"src": p.image->Option.mapOr("", i => i.src)}, []),
+      ReventlessSlots.h(arg.h, "span", Object.make(), [
+        React.string(p.label->Option.getOr("")),
+      ]),
+    ])
+  )
+
+  arg.slots.view(ReventlessSlots.ViewSlot.galleryEmpty, _ =>
+    ReventlessSlots.h(arg.h, "p", Object.make(), [React.string("Nothing here yet.")])
+  )
+}
+```
+
+### Why `h` rather than JSX
+
+Because React is the one thing a slot module must **not** bring its own copy of.
+
+`h` is the shell's own `React.createElement`, handed to you as an argument, so a
+module built through it never imports `react` at all. Everything else it pulls in
+— `@rescript/runtime`, this package — you can bundle freely: those are ordinary
+code with no shared-instance requirement.
+
+JSX is available and nicer to write, but it compiles to `@rescript/react` calls
+that import `react`, which puts you one bundler flag away from shipping a second
+React. Two copies look fine at first — a foreign copy's elements render — right
+up until a renderer calls a hook, where the dispatcher belongs to the other copy
+and it fails with "Invalid hook call". If you want JSX, mark `react` **external**
+and give the page an import map pointing at the shell's copy. `h` simply removes
+the question.
+
+## The slots the shipped surfaces offer
+
+| id | arity | drawn in place of |
+| --- | --- | --- |
+| `cards.face` | row | one card's face: the picture, title, badge and summary fields |
+| `cards.empty` | view | the card grid when the view has no rows |
+| `gallery.tile` | row | one tile: the picture, its caption row and the line under it |
+| `gallery.empty` | view | the tile grid when the view has no rows |
+| `board.card` | row | one card on the board: the title and its one meta line |
+| `tracker.steps` | row | one row's whole progress strip: the step circles and their labels |
+| `tracker.summary` | row | the line beside one row's name; its summary fields |
+| `detail.media` | row | the media column of a `detailLayout: "media"` page; the record's picture |
+| `detail.aside` | row | above the field set on a `detailLayout: "media"` page; nothing by default |
+
+An id nothing offers is reported to the console at boot — a renderer nothing will
+ever call is a mistake the running app would otherwise never mention.
+
+## What you are handed
+
+```ts
+// row slot
+{ row, label?, image?, open?, actions? }
+
+// view slot
+{ rows, total?, selection?, run? }
+```
+
+`row` is the read model's own JSON. `image` is already resolved for this
+deployment's asset origins. `actions` are already resolved against the
+deployment's declarations, the caller's permissions and the row's lifecycle
+state. `open` drills into the row.
+
+`selection` and `run` are declared and filled by nothing yet — cross-row
+selection is its own piece of work. They are in the contract from the start
+because discovering that a region needs a second arity after publishing would be
+a breaking change.
+
+## What a slot may not do
+
+**It renders what it was handed and reads nothing else.** No query of its own, no
+hard-coded command name, no route. The moment a renderer issues its own fetch or
+names a command it stops being a rendering of the generated data plane and
+becomes an application sitting in a shell.
+
+The payloads are narrow so that this is a mechanism rather than a request. The
+producer is the only party that knows the deployment's declarations, the row's
+true identity and what the caller may do; a renderer that could reach the
+producer's own `source` could re-derive all three and get them wrong.
+
+A slot **cannot** add a page, own a route, issue a query or replace a mode. Those
+need compile access to the kit and are not reachable from here.

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@reventlessdev/reventless-ui-slots",
+  "version": "3.0.0-alpha.1",
+  "description": "Types and one runtime helper for writing custom renderers into the regions of Reventless AutoUI's standard view modes.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src/index.js",
+    "src/index.d.ts",
+    "src/**/*.res",
+    "src/**/*.resi",
+    "src/**/*.res.mjs",
+    "rescript.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rescript build",
+    "start": "rescript build -w",
+    "clean": "rescript clean",
+    "test": "rescript build"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "rescript": "^12.3.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "rescript": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "dependencies": {
+    "@rescript/react": "^0.13.1"
+  },
+  "devDependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "rescript": "^12.3.0"
+  },
+  "gitHead": "5877fd93c92d7f3d023e12a9f32e24832b639400"
+}

package/rescript.json

@@ -0,0 +1,26 @@
+{
+  "name": "@reventlessdev/reventless-ui-slots",
+  "jsx": {
+    "version": 4
+  },
+  "sources": [
+    {
+      "dir": "src",
+      "subdirs": true
+    },
+    {
+      "dir": "example",
+      "subdirs": true,
+      "type": "dev"
+    }
+  ],
+  "package-specs": {
+    "module": "esmodule",
+    "in-source": true
+  },
+  "suffix": ".res.mjs",
+  "dependencies": [
+    "@rescript/react"
+  ],
+  "ppx-flags": []
+}

package/src/ReventlessSlots.res

@@ -0,0 +1,67 @@
+// See Slots.resi for the contract. This file is the bindings only — there is no
+// registry here and there cannot be one: the registry lives in the shell, and a
+// slot module receives it as an argument. That is what keeps this package
+// publishable in the open while the kit stays restricted.
+
+type image = {src: string, alt: string}
+
+type action = {label: string, run: unit => unit}
+
+type rowPayload = {
+  row: JSON.t,
+  label?: string,
+  image?: image,
+  @as("open")
+  openRow?: unit => unit,
+  actions?: array<action>,
+}
+
+type viewPayload = {
+  rows: array<JSON.t>,
+  total?: int,
+  selection?: array<string>,
+  run?: string => unit,
+}
+
+type hyperscript
+
+type slots = {
+  row: (string, rowPayload => React.element) => unit,
+  view: (string, viewPayload => React.element) => unit,
+}
+
+type registerArg = {h: hyperscript, slots: slots}
+
+// `React.createElement(tag, props, ...children)` against the function the shell
+// passed in. Written as `%raw` because the callee is a value rather than a
+// module member, which `@variadic` cannot express.
+let h: (hyperscript, 'tag, 'props, array<React.element>) => React.element = %raw(`
+  function (h, tag, props, children) {
+    return h(tag, props, ...children)
+  }
+`)
+
+module RowSlot = {
+  let cardsFace = "cards.face"
+  let galleryTile = "gallery.tile"
+  let boardCard = "board.card"
+  let trackerSteps = "tracker.steps"
+  let trackerSummary = "tracker.summary"
+  let detailMedia = "detail.media"
+  let detailAside = "detail.aside"
+  let all = [
+    cardsFace,
+    galleryTile,
+    boardCard,
+    trackerSteps,
+    trackerSummary,
+    detailMedia,
+    detailAside,
+  ]
+}
+
+module ViewSlot = {
+  let cardsEmpty = "cards.empty"
+  let galleryEmpty = "gallery.empty"
+  let all = [cardsEmpty, galleryEmpty]
+}

package/src/ReventlessSlots.res.mjs

@@ -0,0 +1,63 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+
+let h = (function (h, tag, props, children) {
+    return h(tag, props, ...children)
+  });
+
+let cardsFace = "cards.face";
+
+let galleryTile = "gallery.tile";
+
+let boardCard = "board.card";
+
+let trackerSteps = "tracker.steps";
+
+let trackerSummary = "tracker.summary";
+
+let detailMedia = "detail.media";
+
+let detailAside = "detail.aside";
+
+let all = [
+  cardsFace,
+  galleryTile,
+  boardCard,
+  trackerSteps,
+  trackerSummary,
+  detailMedia,
+  detailAside
+];
+
+let RowSlot = {
+  cardsFace: cardsFace,
+  galleryTile: galleryTile,
+  boardCard: boardCard,
+  trackerSteps: trackerSteps,
+  trackerSummary: trackerSummary,
+  detailMedia: detailMedia,
+  detailAside: detailAside,
+  all: all
+};
+
+let cardsEmpty = "cards.empty";
+
+let galleryEmpty = "gallery.empty";
+
+let all$1 = [
+  cardsEmpty,
+  galleryEmpty
+];
+
+let ViewSlot = {
+  cardsEmpty: cardsEmpty,
+  galleryEmpty: galleryEmpty,
+  all: all$1
+};
+
+export {
+  h,
+  RowSlot,
+  ViewSlot,
+}
+/* No side effect */

package/src/ReventlessSlots.resi

@@ -0,0 +1,129 @@
+/*** The contract a Reventless slot module is written against, for ReScript.
+
+  The same contract `index.d.ts` describes for JavaScript and TypeScript — same
+  payloads, same two registration functions, same module shape. The shell cannot
+  tell what compiled a slot module.
+
+  A slot is a named region *inside* one of AutoUI's standard view modes. The mode
+  keeps everything it owns — paging, the window sentence, the action offers, the
+  drill target, the live-update path — and your renderer replaces what is drawn
+  inside the region. Every slot is optional and a missing one is not an error.
+
+  ⚠️ A slot renders what it was handed and reads nothing else. No query of its
+  own, no hard-coded command name, no route. The payloads are narrow so that this
+  is a mechanism rather than a request: the producer is the only party that knows
+  the deployment's declarations, the row's true identity and what the caller may
+  do, and a renderer that re-derived any of the three would get it wrong. A slot
+  cannot add a page, own a route, issue a query or replace a mode. */
+
+/** A picture the region draws, already resolved: the reference is rebased for
+    this deployment's asset origins, and `alt` is the value's own text where it
+    carried one, falling back to the row's label. */
+type image = {src: string, alt: string}
+
+/** Something to do with this row that is not "open it" — already resolved
+    against the deployment's declarations, the caller's permissions and the row's
+    lifecycle state by the time it reaches you. */
+type action = {label: string, run: unit => unit}
+
+/** What a per-row region is handed. */
+type rowPayload = {
+  /** The row as the producer holds it — the read model's own JSON. */
+  row: JSON.t,
+  /** What the mode would have titled this row. */
+  label?: string,
+  /** The row's picture, where the view resolves one and this row has it. */
+  image?: image,
+  /** Drill into this row. Absent where the producer wired no drill target.
+      Serialized as `open`, which is the name the JS and TS contracts use. */
+  @as("open")
+  openRow?: unit => unit,
+  /** Commands this row can start in the state it is in. */
+  actions?: array<action>,
+}
+
+/** What a per-view region is handed. `selection` and `run` are declared and
+    filled by nothing yet — cross-row selection is its own piece of work. They
+    are in the contract from the start because discovering that a region needs a
+    second arity after publishing would be a breaking change. */
+type viewPayload = {
+  /** The rows the mode is currently drawing — its page window, not the table. */
+  rows: array<JSON.t>,
+  /** How many rows that window holds. */
+  total?: int,
+  /** Row ids the caller has picked out, where the mode offers picking. */
+  selection?: array<string>,
+  /** Start the region's one command, by name. */
+  run?: string => unit,
+}
+
+/** React's `createElement`, as the shell handed it over. */
+type hyperscript
+
+/** The two registration functions, one per arity. A slot id is drawn once per
+    row or once per view, and which one it is is fixed by the mode offering it. */
+type slots = {
+  row: (string, rowPayload => React.element) => unit,
+  view: (string, viewPayload => React.element) => unit,
+}
+
+/** The one argument `register` receives. */
+type registerArg = {h: hyperscript, slots: slots}
+
+/** Build an element with the SHELL's React rather than one of your own.
+
+    Worth preferring over JSX, because React is the one thing a slot module must
+    not bring a second copy of: a foreign copy's elements render fine right up
+    until a renderer calls a hook, where the dispatcher belongs to the other copy
+    and it fails. Built through `h`, the module never imports `react` at all —
+    everything else it pulls in bundles freely.
+
+    JSX compiles to `@rescript/react` calls that import `react`, so a JSX slot
+    module needs `react` marked external plus an import map pointing at the
+    shell's copy.
+
+    ```rescript
+    let register = (arg: ReventlessSlots.registerArg) =>
+      arg.slots.row("gallery.tile", p =>
+        ReventlessSlots.h(arg.h, "button", {"className": "tile"}, [
+          ReventlessSlots.h(arg.h, "img", {"src": p.image->Option.mapOr("", i => i.src)}, []),
+        ])
+      )
+    ```
+*/
+let h: (hyperscript, 'tag, 'props, array<React.element>) => React.element
+
+/** Per-row slots the shipped modes offer. */
+module RowSlot: {
+  /** One card's face: the picture, title, badge and summary fields. */
+  let cardsFace: string
+  /** One tile: the picture, its caption row and the line under it. */
+  let galleryTile: string
+  /** One card on the board: the title and its one meta line. */
+  let boardCard: string
+  /** One row's whole progress strip: the step circles and their labels.
+
+      The strip rather than one step, because a per-node payload would be a third
+      arity in a contract that settled on two — and a step slot with no way to
+      say WHICH step is not a slot at all. */
+  let trackerSteps: string
+  /** The line beside one row's name on the tracker; its summary fields. */
+  let trackerSummary: string
+  /** The media column of a `detailLayout: "media"` page; the record's picture.
+
+      Offered by the drill detail rather than by a view mode — it is the other
+      half of the pair every mode renders under, not a mode itself. */
+  let detailMedia: string
+  /** Above the field set on a `detailLayout: "media"` page; nothing by default. */
+  let detailAside: string
+  let all: array<string>
+}
+
+/** Per-view slots the shipped modes offer. */
+module ViewSlot: {
+  /** The card grid when the view has no rows. */
+  let cardsEmpty: string
+  /** The tile grid when the view has no rows. */
+  let galleryEmpty: string
+  let all: array<string>
+}

package/src/index.d.ts

@@ -0,0 +1,146 @@
+/**
+ * The contract a Reventless slot module is written against.
+ *
+ * A slot is a named region *inside* one of AutoUI's standard view modes. The
+ * mode keeps everything it owns — paging, the window sentence, the action
+ * offers, the drill target, the live-update path — and your renderer replaces
+ * what is drawn inside the region. Every slot is optional: register none and the
+ * mode draws its own rendering, which is what every deployment already sees.
+ *
+ * What a slot may NOT do is the whole of its usefulness. **It renders what it
+ * was handed and reads nothing else.** No query of its own, no hard-coded
+ * command name, no route. The payloads below are narrow on purpose: the producer
+ * is the only party that knows the deployment's declarations, the row's true
+ * identity and what the caller may do, and a renderer that re-derived any of the
+ * three would get it wrong.
+ *
+ * A slot cannot add a page, own a route, issue a query or replace a mode. Those
+ * need compile access to the kit and are not reachable from here.
+ */
+
+/** A picture the region draws, already resolved: the reference is rebased for
+ *  this deployment's asset origins, and `alt` is the value's own text where it
+ *  carried any, falling back to the row's label. */
+export interface SlotImage {
+  src: string
+  alt: string
+}
+
+/** Something to do with this row that is not "open it" — already resolved
+ *  against the deployment's declarations, the caller's permissions and the row's
+ *  lifecycle state by the time it reaches you. Call `run` from a click. */
+export interface SlotAction {
+  label: string
+  run(): void
+}
+
+/** What a per-row region is handed. */
+export interface RowPayload<Row = Record<string, unknown>> {
+  /** The row as the producer holds it — the read model's own JSON. */
+  row: Row
+  /** What the mode would have titled this row. */
+  label?: string
+  /** The row's picture, where the view resolves one and this row has it. */
+  image?: SlotImage
+  /** Drill into this row. Absent where the producer wired no drill target. */
+  open?: () => void
+  /** Commands this row can start in the state it is in. */
+  actions?: SlotAction[]
+}
+
+/** What a per-view region is handed.
+ *
+ *  `selection` and `run` are declared and filled by nothing yet: cross-row
+ *  selection is its own piece of work. They are here from the start because
+ *  discovering that a region needs a second arity after the contract is
+ *  published would be a breaking change. */
+export interface ViewPayload<Row = Record<string, unknown>> {
+  /** The rows the mode is currently drawing — its page window, not the table. */
+  rows: Row[]
+  /** How many rows that window holds. */
+  total?: number
+  /** Row ids the caller has picked out, where the mode offers picking. */
+  selection?: string[]
+  /** Start the region's one command, by name. */
+  run?: (command: string) => void
+}
+
+/** Anything React will render. Deliberately structural — the package declares no
+ *  dependency on React's types, so a slot module needs no React install. */
+export type SlotNode = unknown
+
+export type RowRenderer<Row = Record<string, unknown>> = (payload: RowPayload<Row>) => SlotNode
+export type ViewRenderer<Row = Record<string, unknown>> = (payload: ViewPayload<Row>) => SlotNode
+
+/** The registry handed to `register`. Two functions, one per arity; a slot id is
+ *  drawn once per row or once per view, and which one it is is fixed by the mode
+ *  that offers it. */
+export interface Slots {
+  row(id: RowSlotId | (string & {}), render: RowRenderer): void
+  view(id: ViewSlotId | (string & {}), render: ViewRenderer): void
+}
+
+/** React's own `createElement`, handed over as-is: `h(tag, props, ...children)`.
+ *  It arrives as an argument so a slot module needs no bundler, no React import
+ *  and no version to keep in step with the shell's. */
+export type Hyperscript = (
+  type: unknown,
+  props?: Record<string, unknown> | null,
+  ...children: SlotNode[]
+) => SlotNode
+
+export interface RegisterArg {
+  h: Hyperscript
+  slots: Slots
+}
+
+/** The one export a slot module provides. */
+export type Register = (arg: RegisterArg) => void
+
+/**
+ * Per-row slots the shipped modes offer.
+ *
+ * | id | drawn in place of |
+ * | --- | --- |
+ * | `cards.face` | one card's face: the picture, title, badge and summary fields |
+ * | `gallery.tile` | one tile: the picture, its caption row and the line under it |
+ * | `board.card` | one card on the board: the title and its one meta line |
+ * | `tracker.steps` | one row's whole progress strip: the connected step circles and their labels |
+ * | `tracker.summary` | the line beside one row's name; its summary fields |
+ * | `detail.media` | the media column of a `detailLayout: "media"` page; the record's picture |
+ * | `detail.aside` | above the field set on a `detailLayout: "media"` page; nothing by default |
+ */
+export type RowSlotId =
+  | 'cards.face'
+  | 'gallery.tile'
+  | 'board.card'
+  | 'tracker.steps'
+  | 'tracker.summary'
+  | 'detail.media'
+  | 'detail.aside'
+
+/**
+ * Per-view slots the shipped modes offer.
+ *
+ * | id | drawn in place of |
+ * | --- | --- |
+ * | `cards.empty` | the card grid when the view has no rows |
+ * | `gallery.empty` | the tile grid when the view has no rows |
+ */
+export type ViewSlotId = 'cards.empty' | 'gallery.empty'
+
+/**
+ * Identity helper: type-checks a `register` function without changing it.
+ *
+ * ```js
+ * import { defineSlots } from '@reventlessdev/reventless-ui-slots'
+ *
+ * export const register = defineSlots(({ h, slots }) => {
+ *   slots.row('gallery.tile', ({ row, image, open }) =>
+ *     h('button', { className: 'tile', onClick: open },
+ *       h('img', { src: image?.src, alt: image?.alt ?? '' }),
+ *       h('span', null, row.name)))
+ * })
+ * ```
+ */
+export declare function defineSlots(register: Register): Register

package/src/index.js

@@ -0,0 +1,8 @@
+// The whole runtime of this package. `defineSlots` is the identity function:
+// its only job is to give an editor something to check a `register` export
+// against, which is exactly what a types-and-documentation package is for.
+//
+// A slot module does not need it. `export function register({ h, slots }) {…}`
+// works on its own, because `h` and the registry arrive as arguments and the
+// shell calls the export by name.
+export const defineSlots = register => register