minimojs 1.0.0-alpha.43 → 1.0.0-alpha.44

package/dist/internal/DesignNamingCheck.js

@@ -5,9 +5,10 @@
 // property is misnamed; a property that must be named differently is
 // declared here as an explicit exception.
 //
-// The one exception is a decoration's properties, `DesignOutline`'s
+// The exceptions are a decoration's properties, `DesignOutline`'s
 // `outlineWidth` and `outlineColor` (X-023). They belong to the optional
 // `outline` module, not to the sprite, which the core never gives an outline
 // of its own; in code they are `outlines.set(sprite, { width, color })`, and
-// the prefix says which module reads them in a file.
+// the prefix says which module reads them in a file. And `comment` (X-026),
+// the creator's request to their agent, which no runtime object takes.
 export {};

package/dist/minimo-format.d.ts

@@ -62,6 +62,18 @@ export interface SoundAsset {
  * The grid starts at the image's top-left corner, with no margin or spacing;
  * pixels left over at the right or bottom edge belong to no frame.
  *
+ * Every frame must be clean: its whole figure inside its own cell, with a
+ * transparent margin on every side, and nothing of a neighboring frame in it.
+ * The grid is cut exactly as declared, so a stray piece of a neighbor near a
+ * cell's edge is drawn as part of that frame. This is where agents most often
+ * go wrong, and most often without checking: an image generator does not keep
+ * its figures inside an even grid, and arranging or resizing frames afterwards
+ * pushes pieces across the lines. Lay the sheet out from separate figures,
+ * each centered in its cell, rather than cutting a generated picture along a
+ * grid; make the image exactly as wide and as tall as its columns and rows of
+ * frames; and before declaring it, cut out every frame and check each one on
+ * its own.
+ *
  * @example
  * ```json
  * { "key": "frog", "type": "spritesheet", "src": "assets/frog-frames.png", "frameWidth": 320, "frameHeight": 320 }
@@ -290,6 +302,17 @@ export interface DesignObjectBase {
      * `Sprite.data`. Default: `{}`.
      */
     data?: Record<string, unknown>;
+    /**
+     * The creator's request about this object, written in Studio for the
+     * creator's AI agent, such as `"Remove this cloud"` (X-026). Not empty, and
+     * at most {@link DESIGN_COMMENT_MAX_LENGTH} characters. The engine checks it
+     * and never uses it: the runtime object does not take it.
+     *
+     * An agent that does what a comment asks removes the comment in the same
+     * change, and answers the creator in its conversation, never in the design.
+     * A comment is never a thread and never the agent's own note.
+     */
+    comment?: string;
 }
 /** The properties of every sprite type: `image`, `emoji`, and `text`. */
 export interface DesignSpriteBase extends DesignObjectBase {
@@ -627,6 +650,8 @@ export interface DesignProperty {
      */
     readonly default: unknown;
 }
+/** The most characters a design object's `comment` may hold (X-026). */
+export declare const DESIGN_COMMENT_MAX_LENGTH = 1000;
 /**
  * Every property each type of design object accepts besides `id` and `type`,
  * with its JSON type, whether it is required, and its default.

package/dist/minimo-format.js

@@ -294,6 +294,9 @@ function oneOf(values, defaultValue) {
 const NAME = { name: spec("string", undefined) };
 const TAGS = { tags: spec("string-list", []) };
 const DATA = { data: spec("object", {}) };
+const COMMENT = { comment: spec("string", undefined) };
+/** The most characters a design object's `comment` may hold (X-026). */
+export const DESIGN_COMMENT_MAX_LENGTH = 1000;
 const SPRITE_SPECS = {
     ...NAME,
     ...TAGS,
@@ -317,6 +320,7 @@ const SPRITE_SPECS = {
     bodyOffsetX: spec("number", 0),
     bodyOffsetY: spec("number", 0),
     ...DATA,
+    ...COMMENT,
 };
 const OUTLINE_SPECS = {
     outlineWidth: spec("number", 0),
@@ -370,6 +374,7 @@ const BACKGROUND_SPECS = {
     layer: spec("number", 0),
     fit: oneOf(["none", "stretch", "contain", "cover"], "cover"),
     ...DATA,
+    ...COMMENT,
 };
 const MODULE_SPECS = {
     module: requiredString(),
@@ -523,7 +528,7 @@ export function enabledDecorations(object) {
     });
 }
 /** The properties every module object takes, whatever its module. */
-const MODULE_OBJECT_FIELDS = new Set(["id", "type", "module", "kind", "options", "name", "tags", "data"]);
+const MODULE_OBJECT_FIELDS = new Set(["id", "type", "module", "kind", "options", "name", "tags", "data", "comment"]);
 /** Checks a module object, already checked as a `module`, against its module's schema. */
 function checkModuleObject(object, label, fail) {
     const quoted = (names) => names.map((name) => `"${name}"`).join(", ");
@@ -608,6 +613,8 @@ export function parseDesignObject(json, where, kind = "design object") {
         if (!isValidValue(value, property)) {
             throw fail(`${label} has "${field}" set to ${describe(value)}, but it must be ${describeExpected(property)}.`);
         }
+        if (field === "comment")
+            checkComment(value, label, fail);
         copy[field] = copyJson(value);
     }
     for (const property of properties.values()) {
@@ -619,6 +626,15 @@ export function parseDesignObject(json, where, kind = "design object") {
         checkModuleObject(copy, label, fail);
     return copy;
 }
+/** A comment is the creator's words for their agent: something to read, and not a document. */
+function checkComment(comment, label, fail) {
+    if (comment.trim().length === 0) {
+        throw fail(`${label} has an empty "comment". Remove the property instead: an object without a request has no comment.`);
+    }
+    if (comment.length > DESIGN_COMMENT_MAX_LENGTH) {
+        throw fail(`${label} has a "comment" of ${comment.length} characters, more than the ${DESIGN_COMMENT_MAX_LENGTH} a comment may hold.`);
+    }
+}
 function isValidValue(value, property) {
     if (value === null)
         return property.nullable;

package/dist/minimo.js

@@ -2062,6 +2062,9 @@ export class Game {
         for (const [field, value] of Object.entries(obj)) {
             if (field === "id" || field === "type" || field === "module" || field === "kind" || field === "options")
                 continue;
+            // A comment is the creator's request to their agent, never the sprite's (X-026).
+            if (field === "comment")
+                continue;
             // The module's own tags, such as "fire", stay beside the design's.
             if (field === "tags") {
                 created.tags = [...new Set([...created.tags, ...value])];
@@ -2106,6 +2109,9 @@ export class Game {
         for (const [field, value] of Object.entries(obj)) {
             if (field === "id" || field === "type")
                 continue;
+            // A comment is the creator's request to their agent, never the object's (X-026).
+            if (field === "comment")
+                continue;
             if (field === "size" && created instanceof EmojiSprite)
                 continue;
             if (field === "imageKey" && created instanceof ImageSprite) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimojs",
-  "version": "1.0.0-alpha.43",
+  "version": "1.0.0-alpha.44",
   "description": "MinimoJS v1 — ultra-minimal, flat, deterministic 2D web game engine. Image-first sprites with emoji as a zero-asset alternative, rAF loop, TypeScript-first, LLM-friendly.",
   "type": "module",
   "main": "dist/minimo.js",