@crowdedkingdoms/crowdyjs 18.1.0-dev.1 → 18.2.0-dev.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
 
@@ -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
 
@@ -626,7 +635,8 @@ model in 18.0.0; see [MIGRATION.md](MIGRATION.md).
 ## ck-exec (dev-tier preview)
 
 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
+(stateless, replicated) on execution hosts, on the dev environment only for now, so it needs
+the `@dev` release (`npm install @crowdedkingdoms/crowdyjs@dev`). A player
 connects to one host and calls any node of the app through it:
 
 ```ts
@@ -873,7 +883,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 +1061,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/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/generated/graphql.d.ts

@@ -1096,7 +1096,7 @@ export type AppMarketplaceFilterInput = {
 /** Per-player usage row for studio diagnostics (top spenders / quota utilization): one (player, app) aggregate over a window. */
 export type AppPlayerUsageRow = {
     __typename?: 'AppPlayerUsageRow';
-    /** Player automation units used. */
+    /** Legacy: the removed engines' player automation units. Always 0 for usage since the legacy engines were removed; kept for the API shape until the migration. */
     automationUnits: Scalars['BigInt']['output'];
     /**
      * DEPRECATED. chargedMicrousd / 10,000 truncated toward zero.
@@ -1105,7 +1105,7 @@ export type AppPlayerUsageRow = {
     chargedCents: Scalars['BigInt']['output'];
     /** Micro-USD charged to the player for this app in the window (exact). */
     chargedMicrousd: Scalars['BigInt']['output'];
-    /** Compile submissions. */
+    /** Legacy: compile submissions of the removed player-compute engine (mod builds are not counted). Always 0 for usage since the legacy engines were removed; kept for the API shape until the migration. */
     compileCount: Scalars['Int']['output'];
     /** Player compute units used. */
     computeUnits: Scalars['BigInt']['output'];
@@ -1219,11 +1219,11 @@ export type AppUsageSummary = {
     __typename?: 'AppUsageSummary';
     /** App id (as a string). */
     appId: Scalars['String']['output'];
-    /** Billed autonomous-process compute units over the window (string counter). */
+    /** Legacy: billed compute units of the removed automation engine over the window (string counter). Always 0 for usage since the legacy engines were removed; kept for the API shape until the migration. */
     automationComputeUnits: Scalars['String']['output'];
-    /** Autonomous-process function invocations over the window (string counter). */
+    /** Legacy: function invocations of the removed automation engine over the window (string counter). Always 0 for usage since the legacy engines were removed; kept for the API shape until the migration. */
     automationInvocations: Scalars['String']['output'];
-    /** Autonomous-process (NPC) runs over the window (string counter). */
+    /** Legacy: runs of the removed automation engine over the window (string counter). Always 0 for usage since the legacy engines were removed; kept for the API shape until the migration. */
     automationRuns: Scalars['String']['output'];
     /** Total GraphQL bytes received (string counter). */
     graphqlRecvBytes: Scalars['String']['output'];
@@ -1611,7 +1611,7 @@ export declare enum CheckoutPurpose {
     Donation = "DONATION",
     /** Add funds to an organization wallet. Requires orgId and amountCents, and the caller must hold the org "manage_billing" permission. Credits the org wallet on completion. */
     OrgWalletTopup = "ORG_WALLET_TOPUP",
-    /** Add funds to the caller's own player wallet (player compute P2). Requires amountCents only — any authenticated user may fund their own wallet; no org permission is involved. Credits the player wallet idempotently on completion. */
+    /** Add funds to the caller's own player wallet, which pays for their mods past the monthly trial (see PlayerWallet). Requires amountCents only — any authenticated user may fund their own wallet; no org permission is involved. Credits the player wallet idempotently on completion. */
     PlayerWalletTopup = "PLAYER_WALLET_TOPUP",
     /**
      * Deprecated. Historically a purchase of in-world property tokens. No longer purchasable and rejected at runtime by createCheckout.
@@ -3241,7 +3241,7 @@ export type DefineAppFeatureInput = {
     appId: Scalars['BigInt']['input'];
     /** Optional description of the feature. */
     description?: InputMaybe<Scalars['String']['input']>;
-    /** The feature key (referenced by tier_feature authority rules). */
+    /** The feature key, as ck-exec code reads it among a player's features. */
     featureKey: Scalars['String']['input'];
 };
 /** Identifies a studio-created grid to delete. The default open-by-default world grid and grids that still contain nested child grids cannot be removed. */
@@ -3833,14 +3833,14 @@ export type GetVoxelListInput = {
     /** Address of the chunk whose voxel edits to list. */
     coordinates: ChunkCoordinatesInput;
 };
-/** An app feature key that functions can gate on and tiers can grant. */
+/** An app feature key that access tiers can grant. ck-exec code reads the keys a player's tier grants with `ctx.players().features(player)`. */
 export type GmAppFeature = {
     __typename?: 'GmAppFeature';
     /** The app (tenant) that defines the feature. */
     appId: Scalars['BigInt']['output'];
     /** Optional description of the feature. */
     description: Maybe<Scalars['String']['output']>;
-    /** The feature key (referenced by tier_feature authority rules). */
+    /** The feature key, as ck-exec code reads it among a player's features. */
     featureKey: Scalars['String']['output'];
 };
 /** A grant of a feature key to an access tier. */
@@ -4513,9 +4513,9 @@ export type Mutation = {
     forceLogoutUser: Scalars['Boolean']['output'];
     /** Operator only (is_operator). Deletes the stored deliverability rows for one address (email_status and email_events) and returns how many rows went. Exists so a verification run is not reading the previous run's events, and so an address suppressed by a bounce that has since been fixed can be given another chance. Returns 0 when there was nothing stored. */
     forgetEmailDeliverability: Scalars['Int']['output'];
-    /** Define an app feature key that functions can gate on (via a tier_feature authority rule) and that access tiers can be granted. Idempotent on (app, featureKey). Requires app-admin ('manage_apps'). */
+    /** Define an app feature key that access tiers can be granted. ck-exec code reads the keys a player's tier grants with `ctx.players().features(player)` (scope `players.read`) and gates on them itself. The `gameModel` prefix is a legacy name. Idempotent on (app, featureKey). Requires app-admin ('manage_apps'). */
     gameModelDefineFeature: GmAppFeature;
-    /** Grant a feature key to an access tier, so users on that tier satisfy tier_feature authority checks for it. Requires app-admin ('manage_apps'). */
+    /** Grant a feature key to an access tier, so it is among the features ck-exec code reads with `ctx.players().features(player)` for every player with active access on that tier. The `gameModel` prefix is a legacy name. Requires app-admin ('manage_apps'). */
     gameModelGrantTierFeature: GmTierFeature;
     /** Revoke a feature key from an access tier. Requires app-admin ('manage_apps'). Returns true if a grant was removed. */
     gameModelRevokeTierFeature: Scalars['Boolean']['output'];
@@ -6103,7 +6103,7 @@ export type PlayerUsageCharge = {
     /** The owning player user id. */
     userId: Scalars['BigInt']['output'];
 };
-/** The caller's player wallet (player compute P2, DN-5): a platform-scoped balance funding that player's grid compute across every org/app they play in. Out-of-band from org wallets — player usage never touches an org's money. */
+/** The caller's player wallet: one platform-scoped balance, across every org and app they play in, that pays for the player's mods past their monthly trial (250,000 compute units in each app) and for any Agentic Studio model requests charged to them. Out-of-band from org wallets — player usage never touches an org's money. */
 export type PlayerWallet = {
     __typename?: 'PlayerWallet';
     /**
@@ -6300,7 +6300,7 @@ export type Query = {
     appPlayerMarkupAccrued: Scalars['BigInt']['output'];
     /** Total player rate-card markup credited to this app's org wallet (`markup_payout` rows, mirrored as CREDIT events on the ledger), in micro-USD, exact. Cents-era accruals from before the ledger are included. Requires 'view_billing'. */
     appPlayerMarkupAccruedMicrousd: Scalars['BigInt']['output'];
-    /** Per-player usage aggregate for an app over a trailing window (top spenders / quota utilization, 06 §5): compute units, automation units, compiles, and cents charged per player. Requires 'view_compute_diagnostics'. */
+    /** Per-player usage aggregate for an app over a trailing window (top spenders / quota utilization): the compute units each player's mods used, and what the player was charged for this app. automationUnits and compileCount are legacy and always 0 for usage since the legacy engines were removed. Requires 'view_compute_diagnostics'. */
     appPlayerUsage: Array<AppPlayerUsageRow>;
     /** Shared-environment runtime gate decision plus current hour/day billing-window usage for an app. Read this to learn why an app is not running (runtimeDenialReason). Caller must be a member of the app's org. */
     appRuntimeState: AppRuntimeState;
@@ -6562,7 +6562,7 @@ export type Query = {
     playerSpendCaps: Array<PlayerSpendCap>;
     /** The caller's posted hourly player-usage charges, newest first, optionally filtered by app. Each charge splits platformCents (base rate card) from markupCents (the studio's configured markup) with a per-metric snapshot — players always see what the platform charges and what the studio adds. */
     playerUsageCharges: Array<PlayerUsageCharge>;
-    /** The caller's player wallet, created empty on first access (never null). Platform-scoped: one wallet funds the player's grid compute across every org/app (DN-5); org billing never touches it. Fund it via createCheckout purpose PLAYER_WALLET_TOPUP. */
+    /** The caller's player wallet, created empty on first access (never null). Platform-scoped: one wallet, across every org and app, pays for the player's mods past their monthly trial and any Agentic Studio model requests charged to them; org billing never touches it. Fund it via createCheckout purpose PLAYER_WALLET_TOPUP. */
     playerWalletBalance: PlayerWallet;
     /** The caller's player-wallet ledger, newest first: top-ups, hourly usage debits (per app), auto-recharges, refunds, and adjustments. Usage-debit hours are broken down by playerUsageCharges, whose snapshot splits the platform and studio-markup components. */
     playerWalletTransactions: Array<PlayerWalletTransaction>;
@@ -8375,13 +8375,13 @@ export type VoxelCoordinates = {
     /** Local voxel Z within the chunk (0-15 for in-bounds voxels). */
     z: Scalars['Int']['output'];
 };
-/** Input form of a voxel position LOCAL to its chunk (see VoxelCoordinates). Signed 16-bit integers; in-bounds positions are 0-15 on each axis for a 16x16x16 chunk. */
+/** Input form of a voxel position LOCAL to its chunk (see VoxelCoordinates). Each coordinate is 0-15 on a 16x16x16 chunk, and the voxel writes (updateVoxel, sendVoxelUpdate, updateChunk's voxelStates) refuse any other value. Teleport's voxelAddress, which is not a write, takes any signed 16-bit value. */
 export type VoxelCoordinatesInput = {
-    /** Local voxel X within the chunk (0-15 for in-bounds voxels). */
+    /** Local voxel X within the chunk, 0-15; voxel writes refuse other values. */
     x: Scalars['Int']['input'];
-    /** Local voxel Y within the chunk (0-15 for in-bounds voxels). */
+    /** Local voxel Y within the chunk, 0-15; voxel writes refuse other values. */
     y: Scalars['Int']['input'];
-    /** Local voxel Z within the chunk (0-15 for in-bounds voxels). */
+    /** Local voxel Z within the chunk, 0-15; voxel writes refuse other values. */
     z: Scalars['Int']['input'];
 };
 /** A single voxel's state override stored on a chunk: its local position, its voxel type, and an opaque base64-encoded state blob. */