@theoremjs/react 0.3.4-next.484.g20d8b9d → 0.3.4-next.522.g9e684cd

package/README.md

@@ -276,7 +276,7 @@ import { TheoremDecision } from '@theoremjs/react/ui';
 ```
 
 - `questions` maps each question id to its definition.
-- `images` is optional. It holds pictures every decision sends, by the reference the questions write, such as `<ghs02>` in "Which item matches <ghs02>?". The page sees them and refuses its own image under one of their names.
+- `images` is optional. It holds pictures a decision can send, by reference, such as `<ghs02>` in "Which item matches <ghs02>?". The kernel sends only the ones that the state or a question references. The page sees them and refuses its own image under one of their names.
 - `vault` holds the keys of the profile, by slot.
 - `metadata` is optional. It adds data, such as the signed-in user, to the trace record of each decision.
 
@@ -284,9 +284,9 @@ When the profile sets `maxStateBytes` in its `inputs`, `TheoremDecision` shows t
 
 In one column, the state sits in the middle of the page until you ask for a decision. It then eases up to the top, and the answers appear under it. With `columns`, the state moves to the left instead and the answers fill the right.
 
-A profile whose model takes images (`images: true`, see the TypeSafe options in `docs/contracts/providers.md`) shows a drop area under the state when a question is a box. Each PNG or JPEG dropped there becomes a state field named after the file. The field holds the image's reference, its name in angle brackets: `pantry shelf.jpg` becomes `{ "pantry_shelf": "<pantry_shelf>" }`. The field shows the image, opens it full size in a lightbox when clicked, and can replace it. A question names the field in backticks, such as "Which jar in `pantry_shelf` is open?". TypeSafe reads a reference anywhere it appears as text. The brackets keep a reference from matching an ordinary word. A decision sends only the images its state still names, as `assets`, and the kernel refuses any that are not PNG or JPEG bytes before a request leaves. Pass `defaultImages`, with a `defaultState` that names them, to start with some.
+The page shows a drop area under the state fields when a question is a box or the decision holds images. The model must take images: on TypeSafe, the binding sets `images: true` (see `docs/contracts/providers.md`). Each PNG or JPEG dropped there becomes a state field named after the file. The field holds the image's reference, its name in angle brackets: `pantry shelf.jpg` becomes `{ "pantry_shelf": "<pantry_shelf>" }`. The field shows the image, opens it full size in a lightbox when clicked, and can replace it. A question names the field in backticks, such as "Which jar in `pantry_shelf` is open?". The model reads a reference anywhere in a string, so the brackets keep a reference from matching an ordinary word. A decision sends only the images its state still holds as a field value, as `assets`, and the kernel refuses any that are not PNG or JPEG bytes before a request leaves. Pass `defaultImages`, with a `defaultState` that names them, to start with some.
 
-A box answer is drawn as the part of the image it covers, with its edges beside it as shares of the image. The image is the one the question's `image` gives, a reference or a state field. Without one, it is the one at the field the instructions first name in backticks, such as `chart` in "Where on `chart` would the green apple in `photo` sit?". Without that, it is the first image the state names, or else the first held. Click the cut-out to open the whole image in a lightbox, with the box outlined in `--color-accent` and the rest shaded in `--color-overlay`.
+A box answer is drawn as the part of the image it covers, with its edges beside it as shares of the image. The image is the one the question's `image` gives, a reference or a state field. Without one, it is the decision's only image. When the page cannot tell which image the box is on, it draws the box in a frame that stands for the whole image. Click the cut-out to open the whole image in a lightbox, with the box outlined in `--color-accent` and the rest shaded in `--color-overlay`.
 
 Pass `onQuestion` to open a question where it is set up, such as in an editor. Each answer then has a button that calls it with the question's id.
 

package/client/decision-images.d.ts

@@ -40,11 +40,10 @@ export declare function droppedImages(dropped: readonly (readonly [File, Decisio
     state: Record<string, DecisionJson>;
 };
 /**
- * The image a box answer is drawn on: `field` itself when it is a held reference, else the one at
- * that state field, else the first the state refers to, else the first held. A box answer names no image, so this is the
- * page's best reading of where it points.
+ * The image a box answer is drawn on: the one its question gives, by reference or by the state
+ * field that holds it, else the decision's only image. Otherwise the page cannot tell, so none.
  */
-export declare function boxSource(images: DecisionImages, state: DecisionJson, field?: string): DecisionAsset | undefined;
+export declare function boxSource(images: DecisionImages, state: DecisionJson, image?: string): DecisionAsset | undefined;
 /** A box answer's edges, each a share of the image from its top or left. */
 export type DecisionBox = {
     top: number;

package/client/decision-images.js

@@ -78,16 +78,15 @@ function at(state, path) {
     return value;
 }
 /**
- * The image a box answer is drawn on: `field` itself when it is a held reference, else the one at
- * that state field, else the first the state refers to, else the first held. A box answer names no image, so this is the
- * page's best reading of where it points.
+ * The image a box answer is drawn on: the one its question gives, by reference or by the state
+ * field that holds it, else the decision's only image. Otherwise the page cannot tell, so none.
  */
-export function boxSource(images, state, field) {
-    const names = Object.keys(images);
-    const pointed = field === undefined || field in images ? field : at(state, field);
-    const named = (typeof pointed === 'string' && pointed in images ? pointed : undefined) ??
-        names.find((name) => mentions(state, name));
-    return images[named ?? names[0] ?? ''];
+export function boxSource(images, state, image) {
+    const reference = image === undefined || image in images ? image : at(state, image);
+    if (typeof reference === 'string' && reference in images)
+        return images[reference];
+    const held = Object.values(images);
+    return image === undefined && held.length === 1 ? held[0] : undefined;
 }
 /** The box in an image's pixels, and an outline that stays visible at any size. */
 export function boxRect(box, width, height) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/react",
-  "version": "0.3.4-next.484.g20d8b9d",
+  "version": "0.3.4-next.522.g9e684cd",
   "description": "React bindings for Theorem: headless hooks + transport, an Astryx chat UI, and a Web-standard server handler.",
   "license": "MIT",
   "type": "module",
@@ -60,8 +60,8 @@
     "@stylexjs/stylex": "0.19.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@theoremjs/agents": "^0.3.4-next.484.g20d8b9d",
-    "@theoremjs/web": "^0.3.4-next.484.g20d8b9d"
+    "@theoremjs/agents": "^0.3.4-next.522.g9e684cd",
+    "@theoremjs/web": "^0.3.4-next.522.g9e684cd"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/core": {

package/ui/DecisionAnswers.js

@@ -164,10 +164,10 @@ function BoxCrop({ source, box, caption, }) {
                         setMarked(null);
                 }, media: { src: marked ?? src, alt: t('@theorem.decision.box_marked'), caption }, hasZoom: true })] }));
 }
-/** The box cut from the image its question names, or drawn in a frame that stands for the whole image. */
-function BoxAnswer({ title, aside, detail, answer, field, asked, }) {
+/** The box cut from its image, or drawn in a frame that stands for the whole image when the page cannot tell which. */
+function BoxAnswer({ title, aside, detail, answer, image, asked, }) {
     const t = useLabels();
-    const source = asked && boxSource(asked.images, asked.state, field);
+    const source = asked && boxSource(asked.images, asked.state, image);
     const n = useNumbers();
     const { top, bottom, left, right } = answer.box;
     const edges = t('@theorem.decision.box_edges', {
@@ -212,7 +212,7 @@ function AnswerCard({ question, answer, asked, onQuestion, detail, }) {
         return _jsx(ScoreAnswer, { ...head, answer: answer, labels: question.labels });
     if (answer.type === 'noul')
         return _jsx(NumberAnswer, { ...head, answer: answer });
-    return _jsx(BoxAnswer, { ...head, answer: answer, field: question.field, asked: asked });
+    return _jsx(BoxAnswer, { ...head, answer: answer, image: question.image, asked: asked });
 }
 /**
  * A console's result as it streams in: dimmed while the next one runs, then

package/ui/labels.d.ts

@@ -501,7 +501,7 @@ export declare const THEOREM_UI_CATALOG: {
     };
     readonly '@theorem.decision.confidence': {
         readonly defaultMessage: "{percent} sure";
-        readonly description: "How sure the model is of a choice or score; percent is formatted, e.g. '92%'.";
+        readonly description: "How sure the model is of a choice, score or box; percent is formatted, e.g. '92%'.";
         readonly params: readonly ["percent"];
     };
     readonly '@theorem.decision.option': {

package/ui/labels.js

@@ -464,7 +464,7 @@ export const THEOREM_UI_CATALOG = {
     },
     '@theorem.decision.confidence': {
         defaultMessage: '{percent} sure',
-        description: "How sure the model is of a choice or score; percent is formatted, e.g. '92%'.",
+        description: "How sure the model is of a choice, score or box; percent is formatted, e.g. '92%'.",
         params: ['percent'],
     },
     '@theorem.decision.option': {