@neocompose/cli 0.53.5 → 0.54.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.54.0] - 2026-09-22
+
+- `NeoSortingGroup` has a `SortPoint`: where the group sorts along the transparency sort axis, as a cell offset from the object's origin-cell corner. It defaults to `(0.5, 0)`, the bottom center of the origin cell. Generated Unity classes implement `INeoSortingGroup.SortPoint`, which requires Neo Compose SDK 0.40.0.
+
+## [0.53.7] - 2026-09-22
+
+- Adding a value under a row that stores packed children, such as a new list on an item whose sprite is packed, keeps those children readable in `neo test`, `neo status`, and `neo push --dry-run`. A constructed instance replayed from that row used to receive the child's id instead of its value and fail with "NSFunction argument 1 does not match its declared runtime type."
+- Editing a function's or property's source drops its stale compiled body before local verification. Changing a function's parameters while keeping its `@id` no longer fails with 'Convex project document field "members" has an invalid shape'.
+
+## [0.53.6] - 2026-09-19
+
+- Full project reads, including initial pulls and resyncs, fetch published snapshots directly in bounded pages, reducing Convex requests and duplicate database reads. Normal incremental pulls keep their existing delta transport.
+
 ## [0.53.5] - 2026-09-19
 
 - `neo test` and `neo push --dry-run` compile pending member initializers and their newly authored callable dependencies when a deletion replays a surviving constructed instance. Adding a computed default and deleting an owned row in one push no longer fails with "has no compiled body".

package/dist/neo.mjs

@@ -38465,16 +38465,26 @@ function composeDocumentRecord(recordKind, recordId, authoredFields, baseRecord)
     }
     assertKnownDocumentFields(recordKind, baseRecord.data);
     const base = partitionDocumentFields(recordKind, baseRecord.data);
-    const invalidatesDerivedConstructor = recordKind === "constructor" && !schemaDocumentAuthoredSemanticallyEqual(
+    const derived = Object.entries(base.derived);
+    const authoredEdited = derived.length > 0 && !schemaDocumentAuthoredSemanticallyEqual(
       recordKind,
       baseRecord.data,
       normalizedAuthored
     );
-    if (!invalidatesDerivedConstructor) Object.assign(data, base.derived);
+    for (const [field, value] of derived) {
+      if (authoredEdited && compiledFromAuthoredBody(recordKind, field)) {
+        continue;
+      }
+      data[field] = value;
+    }
     Object.assign(data, base.volatile);
   }
   return { recordKind, recordId, data };
 }
+function compiledFromAuthoredBody(recordKind, field) {
+  if (recordKind === "constructor") return true;
+  return recordKind === "member" && field !== "valueId";
+}
 function assertOnlyAuthoredFields(recordKind, fields) {
   for (const field of Object.keys(fields)) {
     const disposition = fieldDisposition(recordKind, field);
@@ -50022,6 +50032,14 @@ var init_world_system_classes_generated = __esm({
             docsText: "Sort this group against the scene root, ignoring any enclosing sorting group. Maps to SortingGroup.sortAtRoot.",
             requirement: 1 /* Required */,
             schemaKey: "SortAtRoot"
+          },
+          {
+            memberId: "system_c5d39776-03d6-4673-84bb-16ba81ae9e0a",
+            memberKind: "vector2",
+            defaultValue: { x: 0.5, y: 0 },
+            docsText: "Where this group sorts along the camera's transparency sort axis, as an offset from the object's origin-cell corner in cells, like NeoCollider.Offset. It is the group's pivot: put it where the art meets the ground. Moving it never moves the art.",
+            requirement: 1 /* Required */,
+            schemaKey: "SortPoint"
           }
         ],
         worldKind: "sortingGroup"
@@ -50083,7 +50101,7 @@ var init_world_system_classes_generated = __esm({
             memberId: "system_6f32f1f2-83ea-42fc-8647-34ed0946b7f1",
             memberKind: "int",
             defaultValue: null,
-            docsText: "Nudges this sprite's draw order within its object. Added to the order derived from the object's layer group \u2014 it does not replace it. Leave unset for the default order.",
+            docsText: "Added to the object layer's sorting order; it does not replace it. The result competes with every renderer in the sorting layer, or in the enclosing sorting group, and among equal orders the renderer lower on screen draws in front. Leave unset to use the layer's order.",
             minValue: -32768,
             maxValue: 32767,
             schemaKey: "SortingOrder"
@@ -86205,8 +86223,8 @@ __export(project_document_read_exports, {
   readArrayField: () => readArrayField,
   readProjectDocument: () => readProjectDocument,
   readProjectDocumentContentHashHeads: () => readProjectDocumentContentHashHeads,
-  readProjectDocumentManifestPage: () => readProjectDocumentManifestPage,
   readProjectDocumentManifestPageRecords: () => readProjectDocumentManifestPageRecords,
+  readProjectDocumentPage: () => readProjectDocumentPage,
   readProjectDocumentRevisionMarker: () => readProjectDocumentRevisionMarker,
   withStoredValueBase: () => withStoredValueBase
 });
@@ -86224,7 +86242,7 @@ async function fetchProjectDocumentRawChunkedOnce(runner, options = {}) {
       "Chunked project document read received an empty partition key."
     );
   }
-  const firstPageResult = await runner.fetchManifestPage(
+  const firstPageResult = await runner.fetchPage(
     {
       numItems: DOCUMENT_MANIFEST_PAGE_SIZE,
       cursor: null
@@ -86232,7 +86250,7 @@ async function fetchProjectDocumentRawChunkedOnce(runner, options = {}) {
     firstMapKey
   );
   if (firstPageResult === null) return null;
-  const firstPage = readProjectDocumentManifestPage(firstPageResult);
+  const firstPage = readProjectDocumentPage(firstPageResult);
   if (firstPage.metadata === null) {
     throw new Error(
       "Convex project document manifest first page is missing version metadata."
@@ -86244,18 +86262,20 @@ async function fetchProjectDocumentRawChunkedOnce(runner, options = {}) {
   const snapshots = createProjectDocumentSnapshotLoader(
     (ids) => fetchScopedSnapshotBatch(runner, ids, readBase)
   );
-  const rememberRecords = async (records2) => {
+  const rememberRecords = async (page) => {
+    if (page.snapshots !== void 0) snapshots.seed(page.snapshots);
+    const records2 = page.records;
     for (const record6 of records2) {
       recordsByKey.set(`${record6.recordKind} ${record6.recordId}`, record6);
     }
     await snapshots.enqueue(records2.map((record6) => record6.snapshotId));
   };
   try {
-    await rememberRecords(firstPage.records);
+    await rememberRecords(firstPage);
     const fetchRemainingPages = async (mapKey, initialCursor) => {
       let cursor = initialCursor;
       while (cursor !== null) {
-        const pageResult = await runner.fetchManifestPage(
+        const pageResult = await runner.fetchPage(
           {
             numItems: DOCUMENT_MANIFEST_PAGE_SIZE,
             cursor
@@ -86268,15 +86288,15 @@ async function fetchProjectDocumentRawChunkedOnce(runner, options = {}) {
             "Convex project document manifest returned null for a continuation page."
           );
         }
-        const page = readProjectDocumentManifestPage(pageResult);
+        const page = readProjectDocumentPage(pageResult);
         assertProjectReadBase(readBase, page.readBase);
-        await rememberRecords(page.records);
+        await rememberRecords(page);
         cursor = page.continueCursor;
       }
     };
     await fetchRemainingPages(firstMapKey, firstPage.continueCursor);
     for (const mapKey of mapKeys.slice(1)) {
-      const pageResult = await runner.fetchManifestPage(
+      const pageResult = await runner.fetchPage(
         { numItems: DOCUMENT_MANIFEST_PAGE_SIZE, cursor: null },
         mapKey,
         readBase,
@@ -86287,9 +86307,9 @@ async function fetchProjectDocumentRawChunkedOnce(runner, options = {}) {
           `Convex project document manifest returned null for partition "${mapKey ?? "all"}".`
         );
       }
-      const page = readProjectDocumentManifestPage(pageResult);
+      const page = readProjectDocumentPage(pageResult);
       assertProjectReadBase(readBase, page.readBase);
-      await rememberRecords(page.records);
+      await rememberRecords(page);
       await fetchRemainingPages(mapKey, page.continueCursor);
     }
     const snapshotsById = await snapshots.finish();
@@ -86320,7 +86340,8 @@ async function fetchProjectDocumentRawChunkedOnce(runner, options = {}) {
       }
     }
     const records2 = [...recordsByKey.values()];
-    await runner.validateReadBase(readBase);
+    if (options.revisionValidation !== "live-subscription")
+      await runner.validateReadBase(readBase);
     return assembleProjectDocumentRaw({
       version: metadata.version,
       versions: metadata.versions,
@@ -86352,7 +86373,7 @@ async function fetchProjectDocumentPartitionRecords(runner, mapKey, readBase) {
   try {
     let cursor = null;
     do {
-      const pageResult = await runner.fetchManifestPage(
+      const pageResult = await runner.fetchPage(
         { numItems: DOCUMENT_MANIFEST_PAGE_SIZE, cursor },
         mapKey,
         readBase,
@@ -86363,11 +86384,12 @@ async function fetchProjectDocumentPartitionRecords(runner, mapKey, readBase) {
           `Convex project document manifest returned null for partition "${mapKey}".`
         );
       }
-      const page = readProjectDocumentManifestPage(pageResult);
+      const page = readProjectDocumentPage(pageResult);
       assertProjectReadBase(readBase, page.readBase);
       for (const record6 of page.records) {
         recordsByKey.set(`${record6.recordKind} ${record6.recordId}`, record6);
       }
+      if (page.snapshots !== void 0) snapshots.seed(page.snapshots);
       await snapshots.enqueue(page.records.map((record6) => record6.snapshotId));
       cursor = page.continueCursor;
     } while (cursor !== null);
@@ -86393,42 +86415,30 @@ async function fetchProjectDocumentPartitionRecords(runner, mapKey, readBase) {
   }
 }
 async function fetchProjectDocumentValueRecords(runner, valueIds, readBase) {
-  if (runner.fetchValueHeadsPage === void 0) {
+  if (runner.fetchValueSnapshotsPage === void 0) {
     throw new Error(
-      "Partition-scoped document reads require a value-head reader for member defaults."
+      "Partition-scoped document reads require a value-snapshot reader for member defaults."
     );
   }
   const values = /* @__PURE__ */ new Map();
   let cursor = null;
   do {
-    const page = await runner.fetchValueHeadsPage(valueIds, cursor, readBase);
-    if (!isObject4(page)) throw new Error("Value-head page must be an object.");
-    const revision = readProjectDocumentRevisionMarker({
-      documentRevision: page.documentRevision
-    });
-    if (revision === null)
-      throw new Error("Value-head page has no document revision.");
-    assertProjectReadBase(readBase, revision.readBase);
-    if (!Array.isArray(page.snapshotIds) || !page.snapshotIds.every((id2) => typeof id2 === "string"))
-      throw new Error(
-        "Value-head page snapshotIds must be an array of strings."
-      );
-    if (page.continueCursor !== null && typeof page.continueCursor !== "string")
-      throw new Error(
-        "Value-head page continueCursor must be a string or null."
-      );
-    const loaded = await fetchProjectDocumentSnapshots(
-      (ids) => fetchScopedSnapshotBatch(runner, ids, readBase),
-      page.snapshotIds
-    );
-    for (const snapshot of loaded.values()) {
+    const page = readProjectDocumentPage(
+      await runner.fetchValueSnapshotsPage(valueIds, cursor, readBase)
+    );
+    assertProjectReadBase(readBase, page.readBase);
+    if (page.snapshots === void 0)
+      throw new Error("Value snapshot page is missing snapshots.");
+    if (page.continueCursor !== null && page.continueCursor === cursor)
+      throw new Error("Value snapshot page cursor made no progress.");
+    for (const snapshot of page.snapshots) {
       if (snapshot.recordKind !== "value")
-        throw new Error("Value-head page returned a non-value snapshot.");
+        throw new Error("Value snapshot page returned a non-value snapshot.");
       if (snapshot.deleted)
-        throw new Error("Value-head page returned a deleted snapshot.");
+        throw new Error("Value snapshot page returned a deleted snapshot.");
       if (!valueIds.includes(snapshot.recordId))
         throw new Error(
-          `Value-head page returned unrequested value "${snapshot.recordId}".`
+          `Value snapshot page returned unrequested value "${snapshot.recordId}".`
         );
       values.set(snapshot.recordId, snapshot);
     }
@@ -86446,10 +86456,23 @@ async function fetchScopedSnapshotBatch(runner, ids, readBase) {
   assertProjectReadBase(readBase, readProjectReadBase(result.readBase));
   return result;
 }
-function readProjectDocumentManifestPage(value) {
+function readProjectDocumentPage(value) {
   if (!isObject4(value)) {
     throw new Error("Convex project document manifest page must be an object.");
   }
+  let snapshots;
+  if (value.snapshots !== void 0) {
+    if (!Array.isArray(value.snapshots))
+      throw new Error("Snapshot page snapshots must be an array.");
+    const ids = value.snapshots.map((snapshot) => {
+      if (!isObject4(snapshot))
+        throw new Error("Snapshot page entry must be an object.");
+      if (typeof snapshot.id !== "string")
+        throw new Error("Snapshot page entry is missing an id.");
+      return snapshot.id;
+    });
+    snapshots = ids.length === 0 ? [] : readProjectDocumentSnapshotBatch(value, ids);
+  }
   const continueCursor = value.continueCursor;
   if (continueCursor !== null && typeof continueCursor !== "string") {
     throw new Error(
@@ -86472,7 +86495,12 @@ function readProjectDocumentManifestPage(value) {
       releaseChannels: metadata.releaseChannels,
       documentRevision: metadata.documentRevision
     },
-    records: readProjectDocumentManifestRecords(value.records),
+    ...snapshots === void 0 ? {} : { snapshots },
+    records: snapshots === void 0 ? readProjectDocumentManifestRecords(value.records) : snapshots.map((snapshot) => ({
+      recordKind: snapshot.recordKind,
+      recordId: snapshot.recordId,
+      snapshotId: snapshot.id
+    })),
     continueCursor
   };
 }
@@ -86520,7 +86548,7 @@ function readProjectDocumentManifestPageRecords(value) {
   if (!isObject4(value)) {
     throw new Error("Convex project document manifest page must be an object.");
   }
-  return readProjectDocumentManifestRecords(value.records);
+  return readProjectDocumentPage(value).records;
 }
 async function fetchProjectDocumentSnapshots(fetchBatch, snapshotIds) {
   const loader = createProjectDocumentSnapshotLoader(fetchBatch);
@@ -86566,6 +86594,12 @@ function createProjectDocumentSnapshotLoader(fetchBatch) {
     active.add(work);
   };
   return {
+    seed(snapshots) {
+      for (const snapshot of snapshots) {
+        seen.add(snapshot.id);
+        snapshotsById.set(snapshot.id, snapshot);
+      }
+    },
     async enqueue(snapshotIds) {
       checkFailure();
       for (const id2 of snapshotIds) {
@@ -116045,36 +116079,59 @@ function prospectiveInitializerRecordsV4(args) {
   }
   for (const seed of args.authoredValueSeeds) {
     if (seed.valueId === void 0) continue;
-    records2.set(`value:${seed.valueId}`, {
-      recordKind: "value",
-      recordId: seed.valueId,
-      contentHash: "local-seed",
-      deleted: false,
-      data: {
-        id: seed.valueId,
+    setSeedValueRecord(records2, {
+      id: seed.valueId,
+      projectId: args.workspace.config.projectId,
+      ...encodeStoredValueNode(seed),
+      createdAt: 0,
+      updatedAt: 0
+    });
+    for (const row of seed.values ?? []) {
+      setSeedValueRecord(records2, {
+        id: row.id,
         projectId: args.workspace.config.projectId,
-        ...encodeStoredValueNode(seed),
+        ...encodeStoredValueRowFields(row),
         createdAt: 0,
         updatedAt: 0
-      }
-    });
-    for (const row of seed.values ?? []) {
-      records2.set(`value:${row.id}`, {
+      });
+    }
+  }
+  return records2;
+}
+function setSeedValueRecord(records2, data) {
+  const key = `value:${data.id}`;
+  const physical = records2.get(key)?.data;
+  if (isObjectRecord2(physical) && rowCarriesPackedValueContent(physical)) {
+    const row = {
+      projectId: data.projectId,
+      createdAt: 0,
+      updatedAt: 0,
+      ...physical
+    };
+    if (!isMemberValue(row)) {
+      throw new PackedValueEncodingError(
+        `Seeded row "${key}" replaces a row that packs a child but is not a well-formed value row, so its packed children cannot be kept.`
+      );
+    }
+    for (const child of decodePackedValueRow(row).children) {
+      const childKey = `value:${child.id}`;
+      if (records2.has(childKey)) continue;
+      records2.set(childKey, {
         recordKind: "value",
-        recordId: row.id,
+        recordId: child.id,
         contentHash: "local-seed",
         deleted: false,
-        data: {
-          id: row.id,
-          projectId: args.workspace.config.projectId,
-          ...encodeStoredValueRowFields(row),
-          createdAt: 0,
-          updatedAt: 0
-        }
+        data: child
       });
     }
   }
-  return records2;
+  records2.set(key, {
+    recordKind: "value",
+    recordId: data.id,
+    contentHash: "local-seed",
+    deleted: false,
+    data
+  });
 }
 function initializerCode(records2, valueId) {
   const row = records2.get(`value:${valueId}`)?.data;
@@ -133618,7 +133675,7 @@ function readRawSingleton(raw, key) {
 async function fetchProjectDocument(workspace) {
   const convex = await createConvexClient(workspace);
   const raw = await fetchProjectDocumentRawChunked2({
-    fetchManifestPage: (paginationOpts, mapKey, readBase) => convex.query(api2.projectDocuments.getDocumentManifestPage, {
+    fetchPage: (paginationOpts, mapKey, readBase) => convex.query(api2.projectDocuments.getDocumentSnapshotPage, {
       projectId: workspace.config.projectId,
       versionId: workspace.config.versionId,
       paginationOpts,
@@ -138787,7 +138844,7 @@ var init_registry2 = __esm({
   "schema-contract/registry.mjs"() {
     "use strict";
     PROJECT_SCHEMA_CONTRACT = Object.freeze({
-      cliVersion: "0.53.5",
+      cliVersion: "0.54.0",
       projectFileUploadBatchSize: 32,
       documentRecords: {
         member: {
@@ -146608,7 +146665,7 @@ There is no --keep-current: preserving current semantic state defines flatten.
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   if (args.command === "--version") {
-    console.log("0.53.5");
+    console.log("0.54.0");
     return;
   }
   if (args.command === null || args.command === "help" || args.command === "--help" || args.command === "-h") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neocompose/cli",
-  "version": "0.53.5",
+  "version": "0.54.0",
   "description": "Neo Compose native project-source CLI with bidirectional sync.",
   "license": "MIT",
   "type": "module",

package/skills/neocompose-cli/SKILL.md

@@ -9,7 +9,7 @@ description: >-
   `@neocompose/cli` or `node cli/bin/neo.mjs` in the neo-compose repository.
 ---
 
-<!-- reviewed-through-cli: 0.53.5 -->
+<!-- reviewed-through-cli: 0.54.0 -->
 
 # Neo Compose CLI
 

package/skills/neocompose-cli/references/animation-and-world-authoring.md

@@ -209,11 +209,16 @@ class Tree : NeoObject {
 ```
 
 Presence of a non-null group makes the object and descendants sort as one unit.
-`SortAtRoot` hoists a nested group against the scene root.
-
-`NeoSpriteObject` exposes `FlipX`, `FlipY`, `MaskInteraction`, and optional
-`SortingOrder`. Treat `SortingOrder` as an offset added to the order derived
-from layer, placement, and composition; it is not an absolute replacement.
+`SortAtRoot` hoists a nested group against the scene root. `SortPoint` is the
+point the group Y-sorts at, in cells from the object's origin-cell corner
+(default `(0.5, 0)`, the origin cell's bottom center). Moving it never moves
+art. Set it per class, variant, or animation frame, like any other value.
+
+Objects sort by sorting layer, then order in layer, then sort-point Y (lower
+draws in front), then document order. `NeoSpriteObject` exposes `FlipX`,
+`FlipY`, `MaskInteraction`, and optional `SortingOrder`. Treat `SortingOrder`
+as an offset added to the layer's sorting order; it is not an absolute
+replacement.
 
 Use `NeoObjectBase.Enabled` to hide an object and its entire subtree without
 removing its authored `Children` row. A disabled object is not rendered or

package/skills/neocompose-cli/references/cli-development.md

@@ -97,7 +97,7 @@ wrappers.
 The marker near the top of `SKILL.md` must exactly match the package version:
 
 ```html
-<!-- reviewed-through-cli: 0.53.5 -->
+<!-- reviewed-through-cli: 0.54.0 -->
 ```
 
 The quoted version above is checked too, so this instruction cannot go stale