@reventlessdev/reventless-spec 3.0.0-alpha.105 → 3.0.0-alpha.107

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.107 (2026-08-10)
+
+### Bug Fixes
+
+* **core:** collect [@ref](https://github.com/ref) declared on an array field ([6f9e2fe](https://github.com/ReventlessDev/reventless-core/commit/6f9e2fef2568ad57a8bf2efbaa9cd4830a947f26))
+
+
+# 3.0.0-alpha.106 (2026-08-09)
+
+### Features
+
+* **ppx,spec,core:** [@live](https://github.com/live) on state declarations → top-level x-reventless-live schema key ([0f38f38](https://github.com/ReventlessDev/reventless-core/commit/0f38f38dc83c38da2fde6615b89a98cd7fda6fed))
+
+
 # 3.0.0-alpha.105 (2026-08-09)
 
 **Note:** Version bump only for package @reventlessdev/reventless-spec

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.105",
+  "version": "3.0.0-alpha.107",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {

package/src/components/Reference.res

@@ -46,6 +46,35 @@ let getTarget = (schema: S.t<unknown>): option<target> =>
   | _ => None
   }
 
+/**
+The entity a *field* references, wherever inside the field's type the marker sits.
+
+`to_` returns an element schema — a `S.t<string>` — so on `@ref("E") ids:
+array<string>` the ppx annotates the `string` *inside* the array and the field's
+own schema carries nothing. `getTarget` answers `None` there, which is not the
+same as the field declaring no reference: a consumer that finds no declared
+reference falls back to a naming heuristic and resolves the field to whatever
+entity the name suggests, so a dropped `@ref` is a *different* resolution rather
+than a missing one. Any walk collecting a command's or event's references must
+ask this question, not `getTarget`.
+
+Only wrappers around the field's own value are followed — the optional union and
+the array element, to any depth. Object properties are not: a reference declared
+on a nested record's field belongs to that field, and attributing it to the
+enclosing one would name the wrong field.
+*/
+let rec getFieldTarget = (schema: S.t<unknown>): option<target> =>
+  switch getTarget(schema) {
+  | Some(_) as found => found
+  | None =>
+    // `getTarget` already reads through the optional wrapper; the *shape* inside
+    // it still has to be unwrapped here to reach an optional array's element.
+    switch schema->Semantic.unwrapOptional->Option.getOr(schema) {
+    | Array({additionalItems: Schema(item)}) => getFieldTarget(item)
+    | _ => None
+    }
+  }
+
 /**
 Like `to_` but does not imply DCB tag semantics.
 Use with `@ref("Entity") @noDcbTag` when the field references another entity

package/src/components/Reference.res.mjs

@@ -1,6 +1,7 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as S from "sury/src/S.res.mjs";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as DcbTag$Reventless from "./DcbTag.res.mjs";
 import * as Semantic$Reventless from "../semantic/Semantic.res.mjs";
 
@@ -32,6 +33,26 @@ function getTarget(schema) {
   }
 }
 
+function getFieldTarget(_schema) {
+  while (true) {
+    let schema = _schema;
+    let found = getTarget(schema);
+    if (found !== undefined) {
+      return found;
+    }
+    let match = Stdlib_Option.getOr(Semantic$Reventless.unwrapOptional(schema), schema);
+    if (match.type !== "array") {
+      return;
+    }
+    let item = match.additionalItems;
+    if (item === "strip" || item === "strict") {
+      return;
+    }
+    _schema = item;
+    continue;
+  };
+}
+
 function toWithoutDcbTag(plugin, entity) {
   return Semantic$Reventless.mark(S.string, Semantic$Reventless.Id.reference, {
     TAG: "ReferenceTo",
@@ -45,6 +66,7 @@ function toWithoutDcbTag(plugin, entity) {
 export {
   to_,
   getTarget,
+  getFieldTarget,
   toWithoutDcbTag,
 }
 /* S Not a pure module */

package/src/components/StateAnnotations.res

@@ -5,7 +5,8 @@ Spec describing the structural annotations declared on the fields of an
 `@compositeId`, `@subId`, `@compositeSubId`, `@index`), a visibility
 annotation (`@hidden`, `@summary`), a hierarchical-rendering annotation
 (`@drillTarget`, `@collapsed`), a server-query opt-in annotation
-(`@scan`, `@scanSort`), or a UI-list annotation (`@status`, `@groupBy`).
+(`@scan`, `@scanSort`), a UI-list annotation (`@status`, `@groupBy`), or a
+type-level live-updates annotation (`@live` on the `state` declaration).
 Downstream consumers (UI, MCP, codegen) read the
 spec to surface field roles in JSON Schema as `x-reventless-*` extension
 properties.
@@ -86,6 +87,15 @@ type stateAnnotationSpec = {
   the default case is omitted to keep schemas compact.
   */
   visibility: option<string>,
+  /**
+  Component-level live-updates hint from `@live(true | false)` on the
+  `@schema type state` declaration (PPX-emitted). `SuryToJsonSchema.deriveObjectSchema`
+  emits top-level `x-reventless-live: bool` when present; absent annotation ⇒
+  key absent ⇒ the consumer's own default applies. The framework only
+  transports the declaration — UI consumers decide whether a live-updates
+  control is offered (`true`) or hidden (`false`) for the view.
+  */
+  live: option<bool>,
 }
 
 /** Sury metadata ID used to attach a `stateAnnotationSpec` to a state schema. */

package/src/semantic/Semantic.res

@@ -117,39 +117,49 @@ let refined = (base: S.t<'a>, ~id: string, ~check: 'a => result<'a, string>): S.
 let showString = (raw: string): string => raw->JSON.Encode.string->JSON.stringify
 
 /**
-The semantic a field's schema carries, if any.
+The schema an optional field's wrapper stands for, if it is one.
 
-An **optional** field keeps its marker one level down. The ppx annotates the
-field's `string`, and sury-ppx then wraps that schema in a union with
-`Undefined`/`Null`; the wrapper is a new schema and carries no metadata of its
-own. So a walk that reads only the outer schema sees `imageUrl?: string` as
-carrying no semantic at all — the store goes undeclared, the reference goes
-uncollected, the branded scalar loses its brand. Every reader converges here, so
-following the wrapper once here is what keeps "optional" a statement about
-presence rather than a way to lose the field's type.
+sury-ppx compiles `f?: X` to a union of `X`'s schema with `Undefined`/`Null`, and
+that wrapper is a new schema carrying no metadata of its own. Every reader that
+looks *through* a field — for its semantic, or for the element type inside it —
+needs the same one-level unwrap, so it lives here once rather than once per
+reader.
 
-The outer schema is read first, so a marker set on the wrapper itself still wins.
 Only a union with exactly one non-null variant is followed: that is the shape an
 optional field has, and a genuine multi-variant union has no single inner schema
-whose semantic could stand for the whole.
+that could stand for the whole.
 */
-let rec getFrom = (schema: S.t<unknown>): option<t> =>
-  switch S.Metadata.get(schema, ~id=semanticId) {
-  | Some(_) as found => found
-  | None =>
-    switch schema {
-    | Union({anyOf}) =>
-      switch anyOf->Array.filter(v =>
-        switch v {
-        | Null(_) | Undefined(_) => false
-        | _ => true
-        }
-      ) {
-      | [inner] => getFrom(inner)
-      | _ => None
+let unwrapOptional = (schema: S.t<unknown>): option<S.t<unknown>> =>
+  switch schema {
+  | Union({anyOf}) =>
+    switch anyOf->Array.filter(v =>
+      switch v {
+      | Null(_) | Undefined(_) => false
+      | _ => true
       }
+    ) {
+    | [inner] => Some(inner)
     | _ => None
     }
+  | _ => None
+  }
+
+/**
+The semantic a field's schema carries, if any.
+
+An **optional** field keeps its marker one level down, inside the wrapper
+`unwrapOptional` describes. So a walk that reads only the outer schema sees
+`imageUrl?: string` as carrying no semantic at all — the store goes undeclared,
+the reference goes uncollected, the branded scalar loses its brand. Every reader
+converges here, so following the wrapper once here is what keeps "optional" a
+statement about presence rather than a way to lose the field's type.
+
+The outer schema is read first, so a marker set on the wrapper itself still wins.
+*/
+let rec getFrom = (schema: S.t<unknown>): option<t> =>
+  switch S.Metadata.get(schema, ~id=semanticId) {
+  | Some(_) as found => found
+  | None => schema->unwrapOptional->Option.flatMap(getFrom)
   }
 
 let get = (fieldSchema: S.t<'a>): option<t> => fieldSchema->S.castToUnknown->getFrom

package/src/semantic/Semantic.res.mjs

@@ -1,6 +1,7 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as S from "sury/src/S.res.mjs";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 
 let Id = {
   dateTime: "dateTime",
@@ -44,31 +45,33 @@ function showString(raw) {
   return JSON.stringify(raw);
 }
 
-function getFrom(_schema) {
-  while (true) {
-    let schema = _schema;
-    let found = S.Metadata.get(schema, semanticId);
-    if (found !== undefined) {
-      return found;
-    }
-    if (schema.type !== "union") {
-      return;
-    }
-    let match = schema.anyOf.filter(v => {
-      switch (v.type) {
-        case "null" :
-        case "undefined" :
-          return false;
-        default:
-          return true;
-      }
-    });
-    if (match.length !== 1) {
-      return;
+function unwrapOptional(schema) {
+  if (schema.type !== "union") {
+    return;
+  }
+  let match = schema.anyOf.filter(v => {
+    switch (v.type) {
+      case "null" :
+      case "undefined" :
+        return false;
+      default:
+        return true;
     }
-    _schema = match[0];
-    continue;
-  };
+  });
+  if (match.length !== 1) {
+    return;
+  } else {
+    return match[0];
+  }
+}
+
+function getFrom(schema) {
+  let found = S.Metadata.get(schema, semanticId);
+  if (found !== undefined) {
+    return found;
+  } else {
+    return Stdlib_Option.flatMap(unwrapOptional(schema), getFrom);
+  }
 }
 
 let get = getFrom;
@@ -88,6 +91,7 @@ export {
   mark,
   refined,
   showString,
+  unwrapOptional,
   getFrom,
   get,
   has,