@crowdedkingdoms/crowdyjs 18.1.0-dev.1 → 18.2.0-test.1

package/MIGRATION.md

@@ -120,6 +120,25 @@ super-admin's session). There is no SDK replacement.
 `dev`'s SDL after #417 merged (`npm run schema:sync:paths -- --schema <that schema.gql>`, then
 `npm run codegen`).
 
+## 18.2.0: `ChunkStore` keeps the voxel edits it hydrated
+
+No API change. Every voxel write but a chunk write-back lands only in the chunk's edit log: a
+hub's or mod's `world.set_voxels`, `updateVoxel`, and realtime voxel updates. Since ck-api
+`dev/v2.33.0` (cks-game-api #445) `getChunk` returns each recorded edit as a `voxelStates` entry
+with its type, over a stored `voxels` that holds none of them. `ChunkStore` applies them when it
+hydrates a loaded chunk: set `hydrateVoxelStates: true` unless you configure a
+`voxelStateCodec` (the-construct does since construct 0.3.6), or a reload shows none of them.
+(OI-2026-10-02-006)
+
+- `ensureAround` no longer applies a chunk it has already loaded when the bulk load returns it
+  again: the cube around a new center overlaps the old one, and the stored `voxels` put back
+  over the cache wiped the hydrated edits (a hub's block vanished the moment the player crossed
+  into a new chunk) and every realtime merge, and the chunk was never hydrated again. To load a
+  chunk afresh, `pruneBeyond` it first, or call `hydrate(coord)`.
+- `hydrate` puts the entries on a chunk stored with `voxels: null` (a zero grid under them); it
+  used to drop their types. An entry without a state clears the state cached at its voxel, as a
+  realtime merge without one does.
+
 ## 18.1.0: open grids, and where a connect token may go
 
 Additive, except that `client.exec.connect` refuses a gateway it would once have dialed (below).

package/README.md

@@ -12,19 +12,23 @@ gameplay, minted per app through `client.portal`.
 
 Start here:
 
-- [SDK guide](https://docs.crowdedkingdoms.com/crowdyjs/readme) — the canonical
+- [SDK guide](https://docs.dev.crowdedkingdoms.com/crowdyjs/readme) — the canonical
   walkthrough of everything in this README.
-- [Build a game](https://docs.crowdedkingdoms.com/build-a-game/intro) — a
+- [Build a game](https://docs.dev.crowdedkingdoms.com/build-a-game/intro) — a
   hands-on tutorial from sign-in to a playable voxel game.
-- [Platform overview](https://docs.crowdedkingdoms.com/overview/client-workflow)
+- [Platform overview](https://docs.dev.crowdedkingdoms.com/overview/client-workflow)
   — how a client session flows through the platform.
 
 ## Install
 
 ```bash
-npm install @crowdedkingdoms/crowdyjs
+npm install @crowdedkingdoms/crowdyjs@dev
 ```
 
+This README is the `dev` branch's: it documents the release on the `dev` dist-tag
+(`npm view @crowdedkingdoms/crowdyjs dist-tags`), and its links go to the dev docs site. A
+plain `npm install` resolves `latest`, the production release, which has no `client.exec`.
+
 CrowdyJS targets browsers by default and uses native `fetch`, `WebSocket`,
 `crypto`, `btoa`, and `atob`. Node tools can still use the SDK, but must
 provide browser-compatible globals when opening realtime connections (e.g.
@@ -171,8 +175,8 @@ Notes:
 - Use `client.auth.setToken(token)` to seed a token externally (e.g. when
   restoring auth from a non-default storage).
 
-Deeper reading: [Portals & app-scoped tokens](https://docs.crowdedkingdoms.com/management-api/portals-and-app-tokens)
-and [Sign in](https://docs.crowdedkingdoms.com/management-api/authentication).
+Deeper reading: [Portals & app-scoped tokens](https://docs.dev.crowdedkingdoms.com/management-api/portals-and-app-tokens)
+and [Sign in](https://docs.dev.crowdedkingdoms.com/management-api/authentication).
 
 ### Token refresh during gameplay
 
@@ -228,7 +232,7 @@ never told about, so a native refresh without it is a re-placement.
 | `client.host` | Game-host election (`get`, `amIHost`) + actor liveness `heartbeat`. `amIHost` is UI convenience only — a hub decides host-only actions from its caller. |
 | `client.teleport` | Teleport requests. |
 | `client.channels`, `client.teams` | Messaging channels and app-scoped player teams (membership + roles). |
-| `client.exec` | **ck-exec (dev-tier preview):** an app's server code as hubs and spokes. `connect(appId, { nodeType, key })` opens a player's connection to an execution host; the `ExecConnection` it returns has `call`, `callRaw`, `subscribe`, `ping`, `onReconnect` and `close`, with MessagePack payloads, and it reconnects and renews subscriptions by itself. `starters` / `build` / `deploy` build and deploy an app (`manage_compute`); `logs`, `instances`, `versions`, `activateVersion` and `setEnabled` operate it; `mod*` are players' mods on grids they own, and `modClient*`, `gridClientMods`, `consentClientMod`, `trustAuthor`, `revokeClientModConsent` and `revokeAuthorTrust` their CLIENT halves. See [ck-exec](#ck-exec-dev-tier-preview). |
+| `client.exec` | **ck-exec:** an app's server code as hubs and spokes. `connect(appId, { nodeType, key })` opens a player's connection to an execution host; the `ExecConnection` it returns has `call`, `callRaw`, `subscribe`, `ping`, `onReconnect` and `close`, with MessagePack payloads, and it reconnects and renews subscriptions by itself. `starters` / `build` / `deploy` build and deploy an app (`manage_compute`); `logs`, `instances`, `versions`, `activateVersion` and `setEnabled` operate it; `mod*` are players' mods on grids they own, and `modClient*`, `gridClientMods`, `consentClientMod`, `trustAuthor`, `revokeClientModConsent` and `revokeAuthorTrust` their CLIENT halves. See [ck-exec](#ck-exec). |
 | `client.playerWallet` | Player spend: balance, ledger, hourly charges, spend caps, card setup, auto-recharge. A ck-exec mod's compute is billed here, to its owner. |
 | `client.marketplace` | Player-authorized grid claims (`claimGridOwnership`, `claimGridChunk`, `releaseClaimedGrid`, requests and invites) and studio moderation of player code (admission queue, listing administration, claim policy). Mods publish and install through `client.exec`. |
 | `client.crowdyStudio` | Cloud project, personal-library, and common-file APIs for Crowdy Studio: target-scoped files, metadata/module names, optimistic revisions, copy-by-value imports, atomic saves. |
@@ -295,7 +299,7 @@ query AppForRouting($appId: BigInt!) {
 `CrowdyClient` with `httpUrl: gameApiUrl` (and the matching `wsUrl`) holding
 that app's app-scoped token, then drive gameplay through that client. Apps
 with no `gameApiUrl` keep working against the default `httpUrl` you
-configured. See [Loading an app's Game API](https://docs.crowdedkingdoms.com/crowdyjs/shared-environment-routing).
+configured. See [Loading an app's Game API](https://docs.dev.crowdedkingdoms.com/crowdyjs/shared-environment-routing).
 
 ## Realtime notifications
 
@@ -587,6 +591,11 @@ write-back), `channelInbox` / `actorInbox` (message inboxes), `events` (typed
 event router), `host` (host tracking), and `save` / `avatar` (typed durable
 state).
 
+A voxel edit that is not a chunk write-back (a hub's or mod's `world.set_voxels`, `updateVoxel`,
+another player's realtime voxel update) reaches a reload only through hydration: `getChunk`
+returns it in `voxelStates`, and the bulk load's `voxels` never hold it. The store hydrates when
+it has a `voxelStateCodec`; without one, set `chunks: { hydrateVoxelStates: true }`.
+
 A chunk write-back the server refuses (a visitor on someone else's plot, a safe zone, a closed
 wilderness) is dropped, not retried; one that fails for a reason that can clear is tried five
 times. Listen with `session.chunks.onWriteBackFailed(...)` to undo or flag the edit (18.0.4).
@@ -599,7 +608,7 @@ reach your bundle. Reads are synchronous snapshots and writes happen on
 WebSocket events (not `requestAnimationFrame`), so render loops read freely
 and a backgrounded tab keeps ingesting updates; pass `workerTicker()` to also
 keep timer-driven sends at full rate while hidden. See the
-[World Stores guide](https://docs.crowdedkingdoms.com/crowdyjs/stores).
+[World Stores guide](https://docs.dev.crowdedkingdoms.com/crowdyjs/stores).
 
 ## Game Kit
 
@@ -623,11 +632,11 @@ and `runOptimisticAction`, which applies an action locally, asks a referee
 `kit.deploy`, the engines and the model-backed helpers went with the game
 model in 18.0.0; see [MIGRATION.md](MIGRATION.md).
 
-## ck-exec (dev-tier preview)
+## ck-exec
 
 ck-exec runs an app's server code as **hubs** (stateful, one instance per key) and **spokes**
-(stateless, replicated) on execution hosts, on the dev environment only for now. A player
-connects to one host and calls any node of the app through it:
+(stateless, replicated) on execution hosts. A player connects to one host and calls any node
+of the app through it:
 
 ```ts
 // The session token is the app's app-scoped token (client.portal.mintAppToken).
@@ -873,7 +882,7 @@ CLIENT project needs ck-api `v2.25.1` or later. A CLIENT crate still on the lega
 on legacy player compute since 18.0.0.
 
 See [CLIENT halves](https://docs.dev.crowdedkingdoms.com/exec/client-halves), [mods](https://docs.dev.crowdedkingdoms.com/exec/mods)
-and [Embed Crowdy Studio in your game](https://docs.crowdedkingdoms.com/crowdyjs/crowdy-studio-embed).
+and [Embed Crowdy Studio in your game](https://docs.dev.crowdedkingdoms.com/crowdyjs/crowdy-studio-embed).
 
 ### The Studio agent (DeepSeek Harness in the browser)
 
@@ -1051,7 +1060,7 @@ no other repositories and no network access required:
 - `src/generated/graphql.ts` — generated TypeScript operation types.
 
 Schema refresh is explicit, from the published
-[SDL](https://docs.crowdedkingdoms.com/schema/game-api.graphql):
+[SDL](https://docs.dev.crowdedkingdoms.com/schema/game-api.graphql):
 
 ```bash
 npm run schema:sync:prod

package/dist/default-origin.d.ts

@@ -1,6 +1,6 @@
 /**
  * GENERATED — do not edit. The operator tooling's
- * `sync-client-origins.mjs --write --tier dev` writes this file, and
+ * `sync-client-origins.mjs --write --tier test` writes this file, and
  * `check-sdk-default-origin.mjs` refuses it when it names the wrong tier or a
  * host that declaration does not carry. Regenerate; never hand-edit.
  *
@@ -10,14 +10,14 @@
  * than no default at all. Every fallback this SDK ever removed named a host that
  * was already dead. A generated file plus a gate is what makes this one different.
  *
- * Source: the operator's per-tier public CK API origin declaration, tier 'dev'
+ * Source: the operator's per-tier public CK API origin declaration, tier 'test'
  */
 /** The tier this build of the SDK is published for. */
-export declare const CROWDY_DEFAULT_TIER = "dev";
+export declare const CROWDY_DEFAULT_TIER = "test";
 /** The public CK API origin for that tier. */
-export declare const CROWDY_DEFAULT_HTTP_ORIGIN = "https://ck.dev.crowdedkingdoms.com";
+export declare const CROWDY_DEFAULT_HTTP_ORIGIN = "https://ck.test.crowdedkingdoms.com";
 /** The same host over WebSocket. A scheme is composed; a hostname is looked up. */
-export declare const CROWDY_DEFAULT_WS_ORIGIN = "wss://ck.dev.crowdedkingdoms.com";
+export declare const CROWDY_DEFAULT_WS_ORIGIN = "wss://ck.test.crowdedkingdoms.com";
 /** The bare hostname, for callers that need to compare rather than dial. */
-export declare const CROWDY_DEFAULT_HOST = "ck.dev.crowdedkingdoms.com";
+export declare const CROWDY_DEFAULT_HOST = "ck.test.crowdedkingdoms.com";
 //# sourceMappingURL=default-origin.d.ts.map

package/dist/default-origin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"default-origin.d.ts","sourceRoot":"","sources":["../src/default-origin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,uDAAuD;AACvD,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAEzC,8CAA8C;AAC9C,eAAO,MAAM,0BAA0B,uCAAuC,CAAC;AAE/E,mFAAmF;AACnF,eAAO,MAAM,wBAAwB,qCAAqC,CAAC;AAE3E,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,+BAA+B,CAAC"}
+{"version":3,"file":"default-origin.d.ts","sourceRoot":"","sources":["../src/default-origin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,uDAAuD;AACvD,eAAO,MAAM,mBAAmB,SAAS,CAAC;AAE1C,8CAA8C;AAC9C,eAAO,MAAM,0BAA0B,wCAAwC,CAAC;AAEhF,mFAAmF;AACnF,eAAO,MAAM,wBAAwB,sCAAsC,CAAC;AAE5E,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,gCAAgC,CAAC"}

package/dist/default-origin.js

@@ -1,6 +1,6 @@
 /**
  * GENERATED — do not edit. The operator tooling's
- * `sync-client-origins.mjs --write --tier dev` writes this file, and
+ * `sync-client-origins.mjs --write --tier test` writes this file, and
  * `check-sdk-default-origin.mjs` refuses it when it names the wrong tier or a
  * host that declaration does not carry. Regenerate; never hand-edit.
  *
@@ -10,13 +10,13 @@
  * than no default at all. Every fallback this SDK ever removed named a host that
  * was already dead. A generated file plus a gate is what makes this one different.
  *
- * Source: the operator's per-tier public CK API origin declaration, tier 'dev'
+ * Source: the operator's per-tier public CK API origin declaration, tier 'test'
  */
 /** The tier this build of the SDK is published for. */
-export const CROWDY_DEFAULT_TIER = 'dev';
+export const CROWDY_DEFAULT_TIER = 'test';
 /** The public CK API origin for that tier. */
-export const CROWDY_DEFAULT_HTTP_ORIGIN = 'https://ck.dev.crowdedkingdoms.com';
+export const CROWDY_DEFAULT_HTTP_ORIGIN = 'https://ck.test.crowdedkingdoms.com';
 /** The same host over WebSocket. A scheme is composed; a hostname is looked up. */
-export const CROWDY_DEFAULT_WS_ORIGIN = 'wss://ck.dev.crowdedkingdoms.com';
+export const CROWDY_DEFAULT_WS_ORIGIN = 'wss://ck.test.crowdedkingdoms.com';
 /** The bare hostname, for callers that need to compare rather than dial. */
-export const CROWDY_DEFAULT_HOST = 'ck.dev.crowdedkingdoms.com';
+export const CROWDY_DEFAULT_HOST = 'ck.test.crowdedkingdoms.com';

package/dist/domains/admin.d.ts

@@ -17,8 +17,8 @@ import type { GameAppsAPI } from './gameApps.js';
  * instances also reachable at the top level (e.g. `client.billing`), grouped
  * here for discoverability.
  *
- * Operator-only platform operations live separately under `client.operator`
- * (requires `is_operator`).
+ * Platform-operator operations are not in the SDK; it wraps only what a studio
+ * or a player may call.
  *
  * @example
  * ```ts

package/dist/domains/admin.js

@@ -8,8 +8,8 @@
  * instances also reachable at the top level (e.g. `client.billing`), grouped
  * here for discoverability.
  *
- * Operator-only platform operations live separately under `client.operator`
- * (requires `is_operator`).
+ * Platform-operator operations are not in the SDK; it wraps only what a studio
+ * or a player may call.
  *
  * @example
  * ```ts

package/dist/domains/exec.d.ts

@@ -4,7 +4,7 @@ import { CrowdyError } from '../errors.js';
 import { type ExecAppStatusFieldsFragment, type ExecBuildFieldsFragment, type ExecEndpointStatsQuery, type ExecGridClientModFieldsFragment, type ExecInstancesQuery, type ExecLogsQuery, type ExecModClientArtifactQuery, type ExecModClientFieldsFragment, type ExecModFieldsFragment, type ExecModListingFieldsFragment, ExecModScope, type ExecModSwitchFieldsFragment, type ExecVersionsQuery } from '../generated/graphql.js';
 export { ExecModScope };
 /**
- * ck-exec, the hub-and-spoke execution service (dev-tier preview).
+ * ck-exec, the hub-and-spoke execution service.
  *
  * An app's code runs as **hubs** (stateful nodes, one per key, one handler at a
  * time) and **spokes** (stateless, replicated) on execution hosts. A player

package/dist/domains/exec.js

@@ -5,7 +5,7 @@ import { CrowdyError, CrowdyProtocolError } from '../errors.js';
 import { ExecActivateVersionDocument, ExecAppStatusDocument, ExecBuildDocument, ExecBuildStatusDocument, ExecConnectAsDeveloperDocument, ExecConnectDocument, ExecConsentClientModDocument, ExecDeployDocument, ExecEndpointStatsDocument, ExecGridClientModsDocument, ExecInstancesDocument, ExecLogsDocument, ExecAppModsDocument, ExecModBuildDocument, ExecModBuildStatusDocument, ExecModClientArtifactDocument, ExecModClientBuildDocument, ExecModClientDeleteDocument, ExecModClientDeployDocument, ExecModDeleteDocument, ExecModDeployDocument, ExecModInstallDocument, ExecModListingsDocument, ExecModLogsDocument, ExecModPublishDocument, ExecModScope, ExecModSetEnabledDocument, ExecModSetSwitchDocument, ExecModStarterDocument, ExecModSwitchesDocument, ExecModUnpublishDocument, ExecModsDocument, ExecMyModsDocument, ExecRevokeAuthorTrustDocument, ExecRevokeClientModConsentDocument, ExecSetEnabledDocument, ExecStartersDocument, ExecTrustAuthorDocument, ExecVersionsDocument, } from '../generated/graphql.js';
 export { ExecModScope };
 /**
- * ck-exec, the hub-and-spoke execution service (dev-tier preview).
+ * ck-exec, the hub-and-spoke execution service.
  *
  * An app's code runs as **hubs** (stateful nodes, one per key, one handler at a
  * time) and **spokes** (stateless, replicated) on execution hosts. A player