@crowdedkingdoms/crowdyjs 8.2.0 → 8.3.0

package/dist/kit/blueprints/core.d.ts

@@ -0,0 +1,222 @@
+import type { Scalars, SeedContainerInput, SeedContainerTypeInput, SeedEdgeInput, SeedFunctionInput, SeedGameModelInput, SeedPropertyDefInput, UpsertAutomationInput, UpsertAutomationTriggerInput } from '../../generated/graphql.js';
+/**
+ * A composable invoke-policy rule tree, mirroring the server's authority
+ * rules (see the Game API "Game Models → Authority" guide). Serialized with
+ * {@link kitPolicyJson} into the `invokePolicyJson` a function carries.
+ */
+export type KitInvokePolicy = {
+    type: 'allow';
+} | {
+    type: 'owner_of_self';
+} | {
+    type: 'is_host';
+} | {
+    type: 'is_current_turn';
+} | {
+    type: 'is_participant';
+} | {
+    type: 'is_automation';
+} | {
+    type: 'tier_feature';
+    feature: string;
+} | {
+    type: 'group_permission';
+    groupId: string;
+    permission?: string;
+} | {
+    type: 'grid_permission';
+    key: string;
+    gridId?: string;
+} | {
+    type: 'condition';
+    expression: string;
+} | {
+    type: 'and';
+    rules: KitInvokePolicy[];
+} | {
+    type: 'or';
+    rules: KitInvokePolicy[];
+} | {
+    type: 'not';
+    rule: KitInvokePolicy;
+};
+/** Serialize a {@link KitInvokePolicy} tree to the wire `invokePolicyJson`. */
+export declare function kitPolicyJson(policy: KitInvokePolicy): string;
+/**
+ * A grid-permission filter inside a selector: gates selves/candidates by
+ * whether the USER behind each container has/lacks an unexpired runtime grid
+ * permission. Requires a game-api with the permission-read selector support
+ * (v0.13.12+).
+ */
+export interface SelectorPermissionPredicate {
+    /** Where the container's user id comes from: its owner, or a property. */
+    userFrom: 'owner' | {
+        property: string;
+    };
+    op: 'has' | 'lacks';
+    /** Runtime permission key (e.g. 'access', 'update_voxel_data'). */
+    key: string;
+    /** Literal grid id, a property holding one, or omitted for "on ANY grid". */
+    grid?: number | string | {
+        property: string;
+    };
+}
+/**
+ * Typed automation selector (serialized into `selectorJson` at deploy).
+ * Property predicates (`selfWhere`/`where`) filter on model data; permission
+ * predicates (`selfPermissionWhere`/`candidatePermissionWhere`) filter on the
+ * live grid ACL. Extra fields pass through untouched.
+ */
+export interface KitSelectorSpec {
+    selfWhere?: Array<{
+        key: string;
+        op: string;
+        value: unknown;
+    }>;
+    selfPermissionWhere?: SelectorPermissionPredicate[];
+    pick?: 'nearest' | 'lowest' | 'highest' | 'random';
+    ofType?: string;
+    where?: Array<{
+        key: string;
+        op: string;
+        value: unknown;
+    }>;
+    candidatePermissionWhere?: SelectorPermissionPredicate[];
+    by?: 'manhattan' | {
+        property: string;
+    };
+    bindAs?: {
+        ref?: string;
+        x?: string;
+        y?: string;
+        approachX?: string;
+        approachY?: string;
+        approachStop?: number;
+    };
+    [key: string]: unknown;
+}
+/** An automation spec inside a blueprint (the `appId` is bound at deploy). */
+export type KitAutomationSpec = Omit<UpsertAutomationInput, 'appId'>;
+/** An automation event-trigger spec inside a blueprint. */
+export type KitAutomationTriggerSpec = Omit<UpsertAutomationTriggerInput, 'appId'>;
+/**
+ * A **blueprint**: a self-contained, declarative bundle of game-model
+ * definitions (container types, property defs, functions), optional seed
+ * instances, and optional automations that together implement one game
+ * concept (an inventory system, a lockable object, an NPC archetype).
+ *
+ * Blueprints are plain data — build them with {@link inventoryBlueprint},
+ * {@link lockBlueprint}, {@link npcBlueprint}, or by hand — then load them
+ * into an app with `client.kit(appId).deploy([...])` (requires the app-admin
+ * `manage_apps` permission). Deployment is idempotent: seeding upserts
+ * definitions and `upsertAutomation` keys on the automation name.
+ */
+export interface KitBlueprint {
+    /** A short identifier used in error messages (e.g. `'inventory'`). */
+    name: string;
+    containerTypes?: SeedContainerTypeInput[];
+    propertyDefinitions?: SeedPropertyDefInput[];
+    functions?: SeedFunctionInput[];
+    /** Optional shared/world containers to seed (catalog data, world objects). */
+    containers?: SeedContainerInput[];
+    /** Optional edges between seeded containers (by `tempId`). */
+    edges?: SeedEdgeInput[];
+    /** Server-driven automations to upsert after the seed. */
+    automations?: KitAutomationSpec[];
+    /** Event triggers to attach to the automations. */
+    automationTriggers?: KitAutomationTriggerSpec[];
+}
+/** Convert `PascalCase`/`camelCase` to `snake_case` for derived names. */
+export declare function toSnakeCase(name: string): string;
+/** The wire payloads {@link mergeBlueprints} produces for one deployment. */
+export interface MergedBlueprints {
+    seedInput: SeedGameModelInput;
+    automations: UpsertAutomationInput[];
+    automationTriggers: UpsertAutomationTriggerInput[];
+}
+/**
+ * Merge blueprints into a single `gameModelSeed` payload plus the automation
+ * upserts, rejecting duplicate type, property, function, or automation names
+ * across blueprints (a duplicate almost always means two blueprints need
+ * distinct prefixes/type names).
+ */
+export declare function mergeBlueprints(appId: Scalars['BigInt']['input'], blueprints: KitBlueprint[], options?: {
+    sessionId?: string;
+}): MergedBlueprints;
+/**
+ * Concatenate several blueprints into ONE composite blueprint (a plain
+ * client-side merge of the definition arrays — no collision checks; those
+ * happen in {@link mergeBlueprints} at deploy). Used by composite builders
+ * such as `guildBlueprint` that bundle other builders' output under a single
+ * name.
+ */
+export declare function composeBlueprints(name: string, blueprints: KitBlueprint[]): KitBlueprint;
+/**
+ * Who may call a **trusted** mutation (XP grants, score submits, loot rolls,
+ * currency mints, …) — the kit-standard authority shape mirroring
+ * `LockAuthority` (Part of the anti-cheat conventions: reward-granting
+ * functions must never be plain player calls):
+ *
+ * - `'server'` — `invokeScope: "server"`: only app admins may invoke (run it
+ *   from trusted studio/backend code holding `manage_apps`).
+ * - `'host'` — `is_host` policy: the elected host client may invoke.
+ * - `'automation'` — `autonomousInvocable` + `is_automation` policy: only
+ *   server-driven automations may invoke.
+ * - `'owner'` — `owner_of_self`: the owning player (only safe for
+ *   self-limiting functions guarded by conditions).
+ * - `{ custom: rule }` — any hand-written policy rule.
+ */
+export type KitTrustedAuthority = 'server' | 'host' | 'automation' | 'owner' | {
+    custom: KitInvokePolicy;
+};
+/**
+ * The function-level fields a {@link KitTrustedAuthority} compiles to.
+ * `extraCondition` (when given) is AND'ed into the policy.
+ */
+export declare function trustedAuthorityFields(authority: KitTrustedAuthority, extraCondition?: string): Pick<{
+    invokePolicyJson: string;
+    invokeScope?: string;
+    autonomousInvocable?: boolean;
+}, 'invokePolicyJson' | 'invokeScope' | 'autonomousInvocable'>;
+/**
+ * AND extra policy rules into a base policy (skipping empties) — the
+ * composition point for `policyExtra` options such as
+ * `plotBlueprint({ buyPolicyExtra: featureGate('land_owner') })`.
+ */
+export declare function andPolicies(base: KitInvokePolicy, ...extra: Array<KitInvokePolicy | undefined>): KitInvokePolicy;
+/**
+ * A `tier_feature` policy leaf: the caller's access tier must hold `feature`
+ * (defined via `kit.features.define` and granted with
+ * `kit.features.grantToTier`). Pass it to any builder's `*policyExtra`
+ * option to monetization-gate that function.
+ */
+export declare function featureGate(feature: string): KitInvokePolicy;
+/**
+ * How kit types mirror their owner's user id into an `owner_user_id`
+ * property (expressions cannot read container ownership directly).
+ * The kit standard is `'int'`; set `'string'` on a builder only when
+ * integrating with models that mirrored the owner as a string (e.g. Blocks
+ * with Friends) — generated conditions then compare via `to_string(...)`.
+ */
+export type KitOwnerIdKind = 'int' | 'string';
+/**
+ * Expression fragment asserting that `ownerExpr` (an `owner_user_id`-style
+ * property read) equals a user-id expression (usually the injected
+ * `$caller_user_id` / `$self_owner_id` system params), honoring
+ * {@link KitOwnerIdKind}.
+ */
+export declare function ownerEquals(ownerExpr: string, userExpr: string, kind?: KitOwnerIdKind): string;
+/**
+ * Expression fragment asserting that `ownerExpr` (an `owner_user_id`-style
+ * property read) equals the calling user, honoring {@link KitOwnerIdKind}.
+ */
+export declare function ownerEqualsCaller(ownerExpr: string, kind?: KitOwnerIdKind): string;
+/** The `SeedPropertyDefInput` for a kit-standard owner mirror property. */
+export declare function ownerMirrorProperty(containerTypeName: string, kind?: KitOwnerIdKind): {
+    containerTypeName: string;
+    key: string;
+    valueType: string;
+    defaultValueJson: string;
+    description: string;
+};
+//# sourceMappingURL=core.d.ts.map

package/dist/kit/blueprints/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../src/kit/blueprints/core.ts"],"names":[],"mappings":"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"}

package/dist/kit/blueprints/core.js

@@ -0,0 +1,185 @@
+/** Serialize a {@link KitInvokePolicy} tree to the wire `invokePolicyJson`. */
+export function kitPolicyJson(policy) {
+    return JSON.stringify(policy);
+}
+/** Convert `PascalCase`/`camelCase` to `snake_case` for derived names. */
+export function toSnakeCase(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/[\s-]+/g, '_')
+        .toLowerCase();
+}
+/**
+ * Merge blueprints into a single `gameModelSeed` payload plus the automation
+ * upserts, rejecting duplicate type, property, function, or automation names
+ * across blueprints (a duplicate almost always means two blueprints need
+ * distinct prefixes/type names).
+ */
+export function mergeBlueprints(appId, blueprints, options = {}) {
+    const containerTypes = [];
+    const propertyDefinitions = [];
+    const functions = [];
+    const containers = [];
+    const edges = [];
+    const automations = [];
+    const automationTriggers = [];
+    const seenTypes = new Map();
+    const seenProps = new Map();
+    const seenFunctions = new Map();
+    const seenAutomations = new Map();
+    const seenTempIds = new Map();
+    const claim = (seen, key, blueprintName, kind) => {
+        const existing = seen.get(key);
+        if (existing !== undefined) {
+            throw new Error(`Blueprint '${blueprintName}' redefines ${kind} '${key}' already defined by blueprint '${existing}'`);
+        }
+        seen.set(key, blueprintName);
+    };
+    for (const blueprint of blueprints) {
+        for (const type of blueprint.containerTypes ?? []) {
+            claim(seenTypes, type.typeName, blueprint.name, 'container type');
+            containerTypes.push(type);
+        }
+        for (const prop of blueprint.propertyDefinitions ?? []) {
+            claim(seenProps, `${prop.containerTypeName}.${prop.key}`, blueprint.name, 'property');
+            propertyDefinitions.push(prop);
+        }
+        for (const fn of blueprint.functions ?? []) {
+            claim(seenFunctions, fn.name, blueprint.name, 'function');
+            functions.push(fn);
+        }
+        for (const container of blueprint.containers ?? []) {
+            claim(seenTempIds, container.tempId, blueprint.name, 'container tempId');
+            containers.push(container);
+        }
+        edges.push(...(blueprint.edges ?? []));
+        for (const automation of blueprint.automations ?? []) {
+            claim(seenAutomations, automation.name, blueprint.name, 'automation');
+            automations.push({ ...automation, appId });
+        }
+        for (const trigger of blueprint.automationTriggers ?? []) {
+            automationTriggers.push({ ...trigger, appId });
+        }
+    }
+    const seedInput = {
+        appId,
+        ...(options.sessionId !== undefined ? { sessionId: options.sessionId } : {}),
+        ...(containerTypes.length ? { containerTypes } : {}),
+        ...(propertyDefinitions.length ? { propertyDefinitions } : {}),
+        ...(functions.length ? { functions } : {}),
+        ...(containers.length ? { containers } : {}),
+        ...(edges.length ? { edges } : {}),
+    };
+    return { seedInput, automations, automationTriggers };
+}
+/**
+ * Concatenate several blueprints into ONE composite blueprint (a plain
+ * client-side merge of the definition arrays — no collision checks; those
+ * happen in {@link mergeBlueprints} at deploy). Used by composite builders
+ * such as `guildBlueprint` that bundle other builders' output under a single
+ * name.
+ */
+export function composeBlueprints(name, blueprints) {
+    const out = { name };
+    for (const bp of blueprints) {
+        if (bp.containerTypes?.length) {
+            out.containerTypes = [...(out.containerTypes ?? []), ...bp.containerTypes];
+        }
+        if (bp.propertyDefinitions?.length) {
+            out.propertyDefinitions = [
+                ...(out.propertyDefinitions ?? []),
+                ...bp.propertyDefinitions,
+            ];
+        }
+        if (bp.functions?.length) {
+            out.functions = [...(out.functions ?? []), ...bp.functions];
+        }
+        if (bp.containers?.length) {
+            out.containers = [...(out.containers ?? []), ...bp.containers];
+        }
+        if (bp.edges?.length) {
+            out.edges = [...(out.edges ?? []), ...bp.edges];
+        }
+        if (bp.automations?.length) {
+            out.automations = [...(out.automations ?? []), ...bp.automations];
+        }
+        if (bp.automationTriggers?.length) {
+            out.automationTriggers = [
+                ...(out.automationTriggers ?? []),
+                ...bp.automationTriggers,
+            ];
+        }
+    }
+    return out;
+}
+/**
+ * The function-level fields a {@link KitTrustedAuthority} compiles to.
+ * `extraCondition` (when given) is AND'ed into the policy.
+ */
+export function trustedAuthorityFields(authority, extraCondition) {
+    const rule = authority === 'server'
+        ? { type: 'allow' }
+        : authority === 'host'
+            ? { type: 'is_host' }
+            : authority === 'automation'
+                ? { type: 'is_automation' }
+                : authority === 'owner'
+                    ? { type: 'owner_of_self' }
+                    : authority.custom;
+    const policy = extraCondition
+        ? { type: 'and', rules: [rule, { type: 'condition', expression: extraCondition }] }
+        : rule;
+    return {
+        invokePolicyJson: kitPolicyJson(policy),
+        ...(authority === 'server' ? { invokeScope: 'server' } : {}),
+        ...(authority === 'automation' ? { autonomousInvocable: true } : {}),
+    };
+}
+/**
+ * AND extra policy rules into a base policy (skipping empties) — the
+ * composition point for `policyExtra` options such as
+ * `plotBlueprint({ buyPolicyExtra: featureGate('land_owner') })`.
+ */
+export function andPolicies(base, ...extra) {
+    const extras = extra.filter((r) => r !== undefined);
+    if (extras.length === 0)
+        return base;
+    return { type: 'and', rules: [base, ...extras] };
+}
+/**
+ * A `tier_feature` policy leaf: the caller's access tier must hold `feature`
+ * (defined via `kit.features.define` and granted with
+ * `kit.features.grantToTier`). Pass it to any builder's `*policyExtra`
+ * option to monetization-gate that function.
+ */
+export function featureGate(feature) {
+    return { type: 'tier_feature', feature };
+}
+/**
+ * Expression fragment asserting that `ownerExpr` (an `owner_user_id`-style
+ * property read) equals a user-id expression (usually the injected
+ * `$caller_user_id` / `$self_owner_id` system params), honoring
+ * {@link KitOwnerIdKind}.
+ */
+export function ownerEquals(ownerExpr, userExpr, kind = 'int') {
+    return kind === 'string'
+        ? `${ownerExpr} == to_string(${userExpr})`
+        : `${ownerExpr} == ${userExpr}`;
+}
+/**
+ * Expression fragment asserting that `ownerExpr` (an `owner_user_id`-style
+ * property read) equals the calling user, honoring {@link KitOwnerIdKind}.
+ */
+export function ownerEqualsCaller(ownerExpr, kind = 'int') {
+    return ownerEquals(ownerExpr, '$caller_user_id', kind);
+}
+/** The `SeedPropertyDefInput` for a kit-standard owner mirror property. */
+export function ownerMirrorProperty(containerTypeName, kind = 'int') {
+    return {
+        containerTypeName,
+        key: 'owner_user_id',
+        valueType: kind,
+        defaultValueJson: kind === 'string' ? '""' : '0',
+        description: "Mirror of the container owner's user id (kit convention: expressions cannot read container ownership).",
+    };
+}

package/dist/kit/blueprints/decks.d.ts

@@ -0,0 +1,50 @@
+import { type KitBlueprint, type KitOwnerIdKind } from './core.js';
+/** Options for {@link decksBlueprint}. */
+export interface DecksBlueprintOptions {
+    /** Prefix for the type/function names. Defaults to none. */
+    typePrefix?: string;
+    /**
+     * Turn-based mode: adds `is_current_turn` to draw/play/discard, so only
+     * the player whose session turn it is may act. Defaults to false.
+     */
+    turnBased?: boolean;
+    /**
+     * Fan-out cap of the manual shuffle automation (raise it above your
+     * largest deck size). Defaults to 200.
+     */
+    shuffleMaxTargets?: number;
+    /** Owner-mirror typing (see the kit convention). Defaults to `'int'`. */
+    ownerIdKind?: KitOwnerIdKind;
+}
+/** Names derived by {@link decksBlueprint} for a given prefix. */
+export interface DecksNames {
+    cardDefType: string;
+    cardType: string;
+    drawFn: string;
+    playFn: string;
+    discardFn: string;
+    assignPositionFn: string;
+    shuffleAutomation: string;
+}
+/** Compute the type/function names a decks blueprint (and its runtime helper) uses. */
+export declare function decksNames(typePrefix?: string): DecksNames;
+/**
+ * Blueprint for **cards & hidden information**: an admin `CardDef` catalog
+ * and session-scoped `CardInstance`s whose `card_id` carries
+ * **`visibility: "owner"`** — the two-property hidden-info trick: only the
+ * owner's reads include `card_id`, while the public `revealed_card_id` stays
+ * empty until the card is played/discarded (the play function copies it in
+ * the same transaction). Opponents can see a card EXISTS in your hand, not
+ * what it is — enforced by read filtering, not client discipline.
+ *
+ * Shuffling is honest about the platform: expressions can't index arrays, so
+ * decks are ordered by a `position` int dealt by `assign_position`
+ * (`rand_int(0, 1000000)` per card) via a **manual, type-fan-out
+ * automation** — `kit.decks.shuffle()` runs it (admin), and drawing takes
+ * the owner's lowest-position deck card ("top of deck"; the runtime picks
+ * it, the server enforces the zone transition and ownership).
+ *
+ * Runtime counterpart: `client.kit(appId).decks`.
+ */
+export declare function decksBlueprint(options?: DecksBlueprintOptions): KitBlueprint;
+//# sourceMappingURL=decks.d.ts.map

package/dist/kit/blueprints/decks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decks.d.ts","sourceRoot":"","sources":["../../../src/kit/blueprints/decks.ts"],"names":[],"mappings":"AAIA,OAAO,EAKL,KAAK,YAAY,EAEjB,KAAK,cAAc,EACpB,MAAM,WAAW,CAAC;AAEnB,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,yEAAyE;IACzE,WAAW,CAAC,EAAE,cAAc,CAAC;CAC9B;AAED,kEAAkE;AAClE,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,uFAAuF;AACvF,wBAAgB,UAAU,CAAC,UAAU,SAAK,GAAG,UAAU,CAWtD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,YAAY,CAoJhF"}

package/dist/kit/blueprints/decks.js

@@ -0,0 +1,163 @@
+import { kitPolicyJson, ownerMirrorProperty, toSnakeCase, } from './core.js';
+/** Compute the type/function names a decks blueprint (and its runtime helper) uses. */
+export function decksNames(typePrefix = '') {
+    const fnPrefix = typePrefix ? `${toSnakeCase(typePrefix)}_` : '';
+    return {
+        cardDefType: `${typePrefix}CardDef`,
+        cardType: `${typePrefix}CardInstance`,
+        drawFn: `${fnPrefix}draw_card`,
+        playFn: `${fnPrefix}play_card`,
+        discardFn: `${fnPrefix}discard_card`,
+        assignPositionFn: `${fnPrefix}assign_position`,
+        shuffleAutomation: `${fnPrefix.replace(/_/g, '-')}deck-shuffle`,
+    };
+}
+/**
+ * Blueprint for **cards & hidden information**: an admin `CardDef` catalog
+ * and session-scoped `CardInstance`s whose `card_id` carries
+ * **`visibility: "owner"`** — the two-property hidden-info trick: only the
+ * owner's reads include `card_id`, while the public `revealed_card_id` stays
+ * empty until the card is played/discarded (the play function copies it in
+ * the same transaction). Opponents can see a card EXISTS in your hand, not
+ * what it is — enforced by read filtering, not client discipline.
+ *
+ * Shuffling is honest about the platform: expressions can't index arrays, so
+ * decks are ordered by a `position` int dealt by `assign_position`
+ * (`rand_int(0, 1000000)` per card) via a **manual, type-fan-out
+ * automation** — `kit.decks.shuffle()` runs it (admin), and drawing takes
+ * the owner's lowest-position deck card ("top of deck"; the runtime picks
+ * it, the server enforces the zone transition and ownership).
+ *
+ * Runtime counterpart: `client.kit(appId).decks`.
+ */
+export function decksBlueprint(options = {}) {
+    const { typePrefix = '', turnBased = false, shuffleMaxTargets = 200, ownerIdKind: kind = 'int', } = options;
+    const names = decksNames(typePrefix);
+    const playerPolicy = (condition) => {
+        const rules = [
+            { type: 'owner_of_self' },
+            ...(turnBased ? [{ type: 'is_current_turn' }] : []),
+            { type: 'condition', expression: condition },
+        ];
+        return kitPolicyJson({ type: 'and', rules });
+    };
+    const propertyDefinitions = [
+        {
+            containerTypeName: names.cardDefType,
+            key: 'card_id',
+            valueType: 'string',
+            description: 'Stable card identifier (rules data lives on the def).',
+        },
+        ownerMirrorProperty(names.cardType, kind),
+        {
+            containerTypeName: names.cardType,
+            key: 'card_id',
+            valueType: 'string',
+            defaultValueJson: '""',
+            visibility: 'owner',
+            description: "WHICH card this is — owner-visible only (the hidden-information half of the two-property trick); opponents' reads omit it.",
+        },
+        {
+            containerTypeName: names.cardType,
+            key: 'revealed_card_id',
+            valueType: 'string',
+            defaultValueJson: '""',
+            description: 'The public half: empty while the card hides in deck/hand, copied from card_id when played or discarded.',
+        },
+        {
+            containerTypeName: names.cardType,
+            key: 'zone',
+            valueType: 'string',
+            defaultValueJson: '"deck"',
+            description: "Card zone: 'deck' | 'hand' | 'board' | 'discard'.",
+        },
+        {
+            containerTypeName: names.cardType,
+            key: 'position',
+            valueType: 'int',
+            defaultValueJson: '0',
+            description: 'Deck order (lowest = top), dealt by the shuffle automation via rand_int.',
+        },
+    ];
+    const functions = [
+        {
+            name: names.drawFn,
+            containerTypeName: names.cardType,
+            returnType: 'string',
+            mutations: [{ target: 'self', property: 'zone', expression: '"hand"' }],
+            returnExpression: 'self.zone',
+            invokePolicyJson: playerPolicy('self.zone == "deck"'),
+            description: 'Draw a card you own from your deck into your hand (the runtime picks the lowest-position deck card — "top of deck"); card_id stays owner-visible.',
+        },
+        {
+            name: names.playFn,
+            containerTypeName: names.cardType,
+            returnType: 'string',
+            mutations: [
+                { target: 'self', property: 'zone', expression: '"board"' },
+                { target: 'self', property: 'revealed_card_id', expression: 'self.card_id' },
+            ],
+            returnExpression: 'self.revealed_card_id',
+            invokePolicyJson: playerPolicy('self.zone == "hand"'),
+            description: 'Play a card from your hand: the zone flip AND the public reveal (revealed_card_id = card_id) commit together.',
+        },
+        {
+            name: names.discardFn,
+            containerTypeName: names.cardType,
+            returnType: 'string',
+            mutations: [
+                { target: 'self', property: 'zone', expression: '"discard"' },
+                { target: 'self', property: 'revealed_card_id', expression: 'self.card_id' },
+            ],
+            returnExpression: 'self.revealed_card_id',
+            invokePolicyJson: playerPolicy('self.zone == "hand" || self.zone == "board"'),
+            description: 'Discard a card face-up (discard piles are public information).',
+        },
+        {
+            name: names.assignPositionFn,
+            containerTypeName: names.cardType,
+            returnType: 'int',
+            mutations: [
+                { target: 'self', property: 'position', expression: 'rand_int(0, 1000000)' },
+            ],
+            returnExpression: 'self.position',
+            invokePolicyJson: kitPolicyJson({ type: 'is_automation' }),
+            autonomousInvocable: true,
+            description: 'Shuffle step (automation-only): deals this card a random deck position — the supported server-side shuffle pattern (expressions cannot permute arrays).',
+        },
+    ];
+    const automations = [
+        {
+            name: names.shuffleAutomation,
+            functionName: names.assignPositionFn,
+            targetMode: 'type',
+            targetTypeName: names.cardType,
+            triggerType: 'manual',
+            maxTargets: shuffleMaxTargets,
+            selectorJson: JSON.stringify({
+                selfWhere: [{ key: 'zone', op: '==', value: 'deck' }],
+            }),
+            description: 'Manual shuffle: fans assign_position out over every deck-zone card (run via gameModelRunAutomation / kit.decks.shuffle).',
+        },
+    ];
+    return {
+        name: names.cardType,
+        containerTypes: [
+            {
+                typeName: names.cardDefType,
+                displayName: names.cardDefType,
+                instantiableBy: 'admin',
+                description: 'Studio card catalog row.',
+            },
+            {
+                typeName: names.cardType,
+                displayName: names.cardType,
+                instantiableBy: 'member',
+                description: 'One card in play: hidden while in deck/hand (owner-visible card_id), public once revealed.',
+            },
+        ],
+        propertyDefinitions,
+        functions,
+        automations,
+    };
+}