@aethervtt/shard-cards 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Dias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @aethervtt/shard-cards
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Part of [Shard](https://github.com/aethervtt/shard), a WebGPU-first 2D/3D game engine in TypeScript. See the repository for documentation.

package/dist/collection.d.ts

@@ -0,0 +1,35 @@
+export interface CardEntry {
+    instanceId: string;
+    definition: string;
+    faceDown?: boolean;
+}
+/** Logical cards have no entity, texture or per-frame work until a host exposes them. */
+export declare class CardCollection {
+    readonly id: string;
+    private readonly entries;
+    private readonly ids;
+    version: number;
+    constructor(id: string, entries?: readonly CardEntry[]);
+    get count(): number;
+    at(index: number): Readonly<CardEntry> | undefined;
+    insert(entry: CardEntry, index?: number): void;
+    remove(index: number): CardEntry;
+    move(from: number, to: number): void;
+    draw(count: number, destination: CardCollection): void;
+    shuffle(seed: number): void;
+    snapshot(): {
+        id: string;
+        entries: CardEntry[];
+    };
+    private checkIndex;
+}
+export interface CardLayout {
+    kind: 'stack' | 'fan' | 'grid';
+    spacing?: number;
+    columns?: number;
+    angle?: number;
+    width?: number;
+    height?: number;
+}
+/** Writes xyz, then rotation about Z in radians. No allocations. */
+export declare function cardPose(layout: CardLayout, index: number, count: number, out: Float64Array): void;

package/dist/collection.js

@@ -0,0 +1,114 @@
+import { Rng, ShardError } from "@aethervtt/shard-core";
+class CardCollection {
+  id;
+  entries = [];
+  ids = /* @__PURE__ */ new Set();
+  version = 0;
+  constructor(id, entries = []) {
+    this.id = id;
+    for (const entry of entries) this.insert(entry);
+  }
+  get count() {
+    return this.entries.length;
+  }
+  at(index) {
+    return this.entries[index];
+  }
+  insert(entry, index = this.count) {
+    if (!entry.instanceId || this.ids.has(entry.instanceId)) {
+      throw new ShardError("cards/duplicate-id", `Duplicate or empty card ID: ${entry.instanceId}`);
+    }
+    this.checkIndex(index, true);
+    this.entries.splice(index, 0, { ...entry });
+    this.ids.add(entry.instanceId);
+    this.version++;
+  }
+  remove(index) {
+    this.checkIndex(index);
+    const entry = this.entries.splice(index, 1)[0];
+    this.ids.delete(entry.instanceId);
+    this.version++;
+    return entry;
+  }
+  move(from, to) {
+    this.checkIndex(from);
+    this.checkIndex(to);
+    const entry = this.entries.splice(from, 1)[0];
+    this.entries.splice(to, 0, entry);
+    this.version++;
+  }
+  draw(count, destination) {
+    if (destination === this || !Number.isInteger(count) || count < 0 || count > this.count) {
+      throw new ShardError(
+        "cards/invalid-transfer",
+        "Draw needs a distinct destination and an available card count"
+      );
+    }
+    for (let i = 0; i < count; i++) {
+      if (destination.ids.has(this.entries[i].instanceId)) {
+        throw new ShardError(
+          "cards/duplicate-id",
+          `Destination already contains ${this.entries[i].instanceId}`
+        );
+      }
+    }
+    const moved = this.entries.splice(0, count);
+    for (const entry of moved) {
+      this.ids.delete(entry.instanceId);
+      destination.ids.add(entry.instanceId);
+      destination.entries.push(entry);
+    }
+    this.version++;
+    destination.version++;
+  }
+  shuffle(seed) {
+    const rng = new Rng(seed);
+    for (let i = this.count - 1; i > 0; i--) {
+      const range = i + 1;
+      const limit = Math.floor(4294967296 / range) * range;
+      let n;
+      do {
+        n = rng.nextU32();
+      } while (n >= limit);
+      const j = n % range;
+      const a = this.entries[i];
+      this.entries[i] = this.entries[j];
+      this.entries[j] = a;
+    }
+    this.version++;
+  }
+  snapshot() {
+    return { id: this.id, entries: this.entries.map((entry) => ({ ...entry })) };
+  }
+  checkIndex(index, end = false) {
+    if (!Number.isInteger(index) || index < 0 || index >= this.count + Number(end)) {
+      throw new ShardError("cards/invalid-index", `Index ${index} is outside ${this.id}`);
+    }
+  }
+}
+function cardPose(layout, index, count, out) {
+  const width = layout.width ?? 0.063;
+  const height = layout.height ?? 0.088;
+  const spacing = layout.spacing ?? 8e-3;
+  out[0] = out[1] = out[2] = out[3] = 0;
+  if (layout.kind === "stack") {
+    out[2] = index * (layout.spacing ?? 35e-5);
+    return;
+  }
+  if (layout.kind === "grid") {
+    const cols = Math.max(1, Math.floor(layout.columns ?? 5));
+    out[0] = (index % cols - (Math.min(cols, count) - 1) / 2) * (width + spacing);
+    out[1] = -Math.floor(index / cols) * (height + spacing);
+    return;
+  }
+  const a = (count < 2 ? 0 : index / (count - 1) - 0.5) * (layout.angle ?? 45) * Math.PI / 180;
+  const radius = Math.max(height, count * spacing);
+  out[0] = Math.sin(a) * radius;
+  out[1] = (Math.cos(a) - 1) * radius;
+  out[2] = index * 4e-4;
+  out[3] = -a;
+}
+export {
+  CardCollection,
+  cardPose
+};

package/dist/definition.d.ts

@@ -0,0 +1,75 @@
+import { type Infer } from '@aethervtt/shard-core';
+/** Data assets and runtime definitions use the same schema. */
+export declare const CardDefinition: import("@aethervtt/shard-assets").DataType<{
+    readonly label: import("@aethervtt/shard-core").FieldType<string, "object">;
+    readonly size: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+    readonly cornerRadius: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly thickness: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly edgeColor: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
+    readonly front: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+        art: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"Texture"> | null, "object">;
+        fit: import("@aethervtt/shard-core").FieldType<"contain" | "cover" | "stretch", "u8">;
+        background: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
+        uvRect: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec4, "f32">;
+        rotation: import("@aethervtt/shard-core").FieldType<number, "u8">;
+        finishes: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+            family: import("@aethervtt/shard-core").FieldType<string, "object">;
+            strength: import("@aethervtt/shard-core").FieldType<number, "f32">;
+            mask: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+                texture: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"Texture"> | null, "object">;
+                channel: import("@aethervtt/shard-core").FieldType<"a" | "b" | "g" | "r", "u8">;
+                space: import("@aethervtt/shard-core").FieldType<"art" | "face", "u8">;
+                invert: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+                scale: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+                offset: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+            }>, "object">;
+            parameters: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").JsonValue, "object">;
+        }>[], "object">;
+    }>, "object">;
+    readonly back: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+        art: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"Texture"> | null, "object">;
+        fit: import("@aethervtt/shard-core").FieldType<"contain" | "cover" | "stretch", "u8">;
+        background: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
+        uvRect: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec4, "f32">;
+        rotation: import("@aethervtt/shard-core").FieldType<number, "u8">;
+        finishes: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+            family: import("@aethervtt/shard-core").FieldType<string, "object">;
+            strength: import("@aethervtt/shard-core").FieldType<number, "f32">;
+            mask: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+                texture: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"Texture"> | null, "object">;
+                channel: import("@aethervtt/shard-core").FieldType<"a" | "b" | "g" | "r", "u8">;
+                space: import("@aethervtt/shard-core").FieldType<"art" | "face", "u8">;
+                invert: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+                scale: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+                offset: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+            }>, "object">;
+            parameters: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").JsonValue, "object">;
+        }>[], "object">;
+    }>, "object">;
+}, "cards/CardDefinition">;
+export type CardDefinitionValue = Infer<typeof CardDefinition>;
+export type CardFace = CardDefinitionValue['front'];
+export type CardFinishLayer = CardFace['finishes'][number];
+export declare const CARD_SIZES: {
+    readonly poker: readonly [0.063, 0.088];
+    readonly bridge: readonly [0.057, 0.088];
+    readonly tarot: readonly [0.07, 0.12];
+};
+export declare function cardDefinition(json: unknown): CardDefinitionValue;
+export declare const Card: import("@aethervtt/shard-core").ComponentDef<{
+    readonly instanceId: import("@aethervtt/shard-core").FieldType<string, "object">;
+    readonly definition: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"cards/CardDefinition"> | null, "object">;
+    readonly seed: import("@aethervtt/shard-core").FieldType<number, "u32">;
+    readonly finishStrength: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly enabled: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+}>;
+export declare const CardTilt: import("@aethervtt/shard-core").ComponentDef<{
+    readonly enabled: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly maxDegrees: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+    readonly responseSeconds: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly returnSeconds: import("@aethervtt/shard-core").FieldType<number, "f32">;
+}>;
+export declare const CardInteraction: import("@aethervtt/shard-core").ComponentDef<{
+    readonly enabled: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly draggable: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+}>;

package/dist/definition.js

@@ -0,0 +1,87 @@
+import { defineDataType } from "@aethervtt/shard-assets";
+import { defineComponent, ShardError, t } from "@aethervtt/shard-core";
+const mask = t.struct({
+  texture: t.handle("Texture"),
+  channel: t.enum(["r", "g", "b", "a"]),
+  space: t.enum(["face", "art"]),
+  invert: t.bool(),
+  scale: t.vec2({ default: [1, 1] }),
+  offset: t.vec2()
+});
+const layer = t.struct({
+  family: t.string({ default: "cards/rainbow" }),
+  strength: t.f32({ default: 0.65, min: 0, max: 1 }),
+  mask,
+  parameters: t.json({ default: {} })
+});
+const face = t.struct({
+  art: t.handle("Texture"),
+  fit: t.enum(["contain", "cover", "stretch"]),
+  background: t.color({ default: [0.025, 0.03, 0.045, 1] }),
+  uvRect: t.vec4({ default: [0, 0, 1, 1] }),
+  rotation: t.u8({ min: 0, max: 3 }),
+  finishes: t.list(layer)
+});
+const CardDefinition = defineDataType(
+  "cards/CardDefinition",
+  {
+    label: t.string(),
+    size: t.vec2({ default: [0.063, 0.088], unit: "m" }),
+    cornerRadius: t.f32({ default: 3e-3, min: 0, unit: "m" }),
+    thickness: t.f32({ default: 3e-4, min: 0, unit: "m" }),
+    edgeColor: t.color({ default: [0.26, 0.28, 0.34, 1] }),
+    front: face,
+    back: face
+  },
+  {
+    extension: "card",
+    description: "Two-sided printed card with independently masked foil layers."
+  }
+);
+const CARD_SIZES = {
+  poker: [0.063, 0.088],
+  bridge: [0.057, 0.088],
+  tarot: [0.07, 0.12]
+};
+function cardDefinition(json) {
+  const value = CardDefinition.deserialize(json);
+  if (value.size[0] <= 0 || value.size[1] <= 0 || value.cornerRadius > Math.min(value.size[0], value.size[1]) / 2) {
+    throw new ShardError(
+      "cards/invalid-size",
+      "Card dimensions must be positive and fit the corner radius",
+      {
+        path: "/size",
+        hint: "Use dimensions in metres; poker is [0.063, 0.088]."
+      }
+    );
+  }
+  if (value.front.finishes.length > 4 || value.back.finishes.length > 4) {
+    throw new ShardError("cards/layer-limit", "Each face supports up to four independent finishes");
+  }
+  return value;
+}
+const Card = defineComponent("cards/Card", {
+  instanceId: t.string(),
+  definition: t.handle("cards/CardDefinition"),
+  seed: t.u32(),
+  finishStrength: t.f32({ default: 1, min: 0, max: 2 }),
+  enabled: t.bool({ default: true })
+});
+const CardTilt = defineComponent("cards/Tilt", {
+  enabled: t.bool({ default: false }),
+  maxDegrees: t.vec2({ default: [8, 8] }),
+  responseSeconds: t.f32({ default: 0.12, min: 0 }),
+  returnSeconds: t.f32({ default: 0.18, min: 0 })
+});
+const CardInteraction = defineComponent("cards/Interaction", {
+  enabled: t.bool({ default: true }),
+  draggable: t.bool({ default: false })
+});
+export {
+  CARD_SIZES,
+  Card,
+  CardDefinition,
+  CardInteraction,
+  CardTilt,
+  cardDefinition
+};

package/dist/finishes.d.ts

@@ -0,0 +1,27 @@
+import { defineSchema, type Fields } from '@aethervtt/shard-core';
+export interface CardFinishOptions {
+    /** Up to four scalar parameters, packed from this schema in declaration order. */
+    fields?: Fields;
+    /** WESL function body. Inputs: ctx (CardFinishContext), base (linear RGB). Return linear RGB reflectance (clamped to [0, 1] in PBR). */
+    surface: string;
+    /** Optional WESL body: ctx and current (metallic, roughness); return vec2f.
+     * Coverage blends this response alongside surface color. Never emits light.
+     * Default foil response is metallic 0.35, roughness 0.28. Unlit ignores it.
+     */
+    response?: string;
+    baseline?: 'same' | 'unsupported';
+    animated?: false | {
+        fps: number;
+    };
+    description?: string;
+}
+export interface CardFinish {
+    readonly name: string;
+    readonly options: CardFinishOptions;
+    readonly schema: ReturnType<typeof defineSchema>;
+    readonly keys: readonly string[];
+}
+/** No global registration: each cardsPlugin owns its finish library. */
+export declare function defineCardFinish(name: string, options: CardFinishOptions): CardFinish;
+/** Constructed when the plugin is installed; importing cards registers no shader/material. */
+export declare function builtinCardFinishes(): CardFinish[];

package/dist/finishes.js

@@ -0,0 +1,79 @@
+import { defineSchema, ShardError, t } from "@aethervtt/shard-core";
+function defineCardFinish(name, options) {
+  if (!/^[\w-]+\/[\w-]+$/.test(name) || !options.surface.trim()) {
+    throw new ShardError(
+      "cards/invalid-finish",
+      "A finish needs a namespaced name and a WESL surface body"
+    );
+  }
+  const fields = options.fields ?? {};
+  if (options.animated && (!Number.isFinite(options.animated.fps) || options.animated.fps <= 0 || options.animated.fps > 60)) {
+    throw new ShardError(
+      "cards/finish-animation",
+      "Animated finishes must request a frame rate between 0 and 60 FPS, exclusive of zero"
+    );
+  }
+  const keys = Object.keys(fields);
+  if (keys.length > 4 || keys.some((key) => fields[key].kind !== "f32")) {
+    throw new ShardError("cards/finish-fields", "A finish accepts up to four f32 parameters");
+  }
+  const [namespace, local] = name.split("/");
+  const schemaName = `${namespace}/${local[0].toUpperCase()}${local.slice(1).replace(/-([a-z])/g, (_, c) => c.toUpperCase())}Params`;
+  return { name, options, keys, schema: defineSchema(schemaName, fields) };
+}
+function builtinCardFinishes() {
+  return [
+    defineCardFinish("cards/metallic", {
+      fields: {
+        roughness: t.f32({ default: 0.3, min: 0.05, max: 1 }),
+        warmth: t.f32({ default: 0.6 })
+      },
+      response: "return vec2f(0.75, ctx.params.x);",
+      surface: `
+        let shine = pow(max(0.0, dot(ctx.normal, normalize(ctx.view + ctx.light))), mix(110.0, 9.0, ctx.params.x));
+        let tint = mix(vec3f(0.7, 0.85, 1.0), vec3f(1.0, 0.65, 0.18), ctx.params.y);
+        return base * (0.65 + 0.35 * ctx.facing) + tint * (shine * 1.2 + ctx.grazing * 0.25);`
+    }),
+    defineCardFinish("cards/rainbow", {
+      fields: {
+        scale: t.f32({ default: 2.5 }),
+        phase: t.f32(),
+        roughness: t.f32({ default: 0.25 })
+      },
+      response: "return vec2f(0.35, ctx.params.z);",
+      surface: `
+        let p = ctx.uv.x * 0.65 + ctx.uv.y + ctx.shift.x * 0.7 + ctx.shift.y * 0.4;
+        let rainbow = card_spectrum(p * ctx.params.x + ctx.params.y);
+        return base * (0.82 + rainbow * 0.32) + rainbow * (0.08 + ctx.glare * 0.7 + ctx.grazing * 0.2);`
+    }),
+    defineCardFinish("cards/hologram", {
+      fields: { roughness: t.f32({ default: 0.25 }), scale: t.f32({ default: 3 }), phase: t.f32() },
+      response: "return vec2f(0.4, ctx.params.x);",
+      surface: `
+        let wave = sin((ctx.uv.x * 1.3 + ctx.uv.y * 0.7) * 30.0 + ctx.shift.x * 8.0);
+        let hue = dot(ctx.uv, vec2f(0.4, 1.0)) * ctx.params.y + ctx.shift.x * 0.8 - ctx.shift.y * 0.5;
+        let foil = card_spectrum(hue + ctx.params.z + wave * 0.09);
+        return base * (0.72 + foil * 0.45) + foil * (0.14 + ctx.glare * 0.9);`
+    }),
+    defineCardFinish("cards/sparkle", {
+      fields: {
+        density: t.f32({ default: 120, min: 1, max: 300 }),
+        phase: t.f32(),
+        intensity: t.f32({ default: 1 })
+      },
+      surface: `
+        let cell = floor(ctx.uv * ctx.params.x);
+        let rnd = card_hash(cell + vec2f(ctx.seed));
+        let pos = fract(ctx.uv * ctx.params.x) - vec2f(0.5);
+        let pulse = pow(max(0.0, sin(rnd * 120.0 + dot(ctx.shift, vec2f(12.0, 9.0)) + ctx.params.y)), 18.0);
+        let star = exp(-length(pos) * 18.0) + exp(-abs(pos.x) * 65.0 - abs(pos.y) * 9.0) * 0.4;
+        let filtered = 1.0 - smoothstep(0.5, 1.5, max(ctx.footprint.x, ctx.footprint.y) * ctx.params.x);
+        let glitter = star * pulse * filtered * ctx.params.z * 2.5;
+        return base + mix(vec3f(1.0), card_spectrum(rnd + ctx.shift.x), 0.55) * glitter;`
+    })
+  ];
+}
+export {
+  builtinCardFinishes,
+  defineCardFinish
+};

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { CardCollection, type CardEntry, type CardLayout, cardPose } from './collection.js';
+export { CARD_SIZES, Card, CardDefinition, type CardDefinitionValue, type CardFace, type CardFinishLayer, CardInteraction, CardTilt, cardDefinition, } from './definition.js';
+export { builtinCardFinishes, type CardFinish, type CardFinishOptions, defineCardFinish, } from './finishes.js';
+export { cardMesh } from './mesh.js';
+export { CardAutomaticMotion, type CardAutomaticMotionValue, sampleCardMotion } from './motion.js';
+export { type CardsPluginOptions, cardsPlugin } from './plugin.js';
+export { CardHandle, type CardHit, type CardPose, Cards, CardTableState, cardTiltCoordinates, createCardHit, hitCards, } from './table.js';
+export { type CardImage, type CardTexturePage, prepareCardTextures } from './textures.js';

package/dist/index.js

@@ -0,0 +1,48 @@
+import { CardCollection, cardPose } from "./collection.js";
+import {
+  CARD_SIZES,
+  Card,
+  CardDefinition,
+  CardInteraction,
+  CardTilt,
+  cardDefinition
+} from "./definition.js";
+import {
+  builtinCardFinishes,
+  defineCardFinish
+} from "./finishes.js";
+import { cardMesh } from "./mesh.js";
+import { CardAutomaticMotion, sampleCardMotion } from "./motion.js";
+import { cardsPlugin } from "./plugin.js";
+import {
+  CardHandle,
+  Cards,
+  CardTableState,
+  cardTiltCoordinates,
+  createCardHit,
+  hitCards
+} from "./table.js";
+import { prepareCardTextures } from "./textures.js";
+export {
+  CARD_SIZES,
+  Card,
+  CardAutomaticMotion,
+  CardCollection,
+  CardDefinition,
+  CardHandle,
+  CardInteraction,
+  CardTableState,
+  CardTilt,
+  Cards,
+  builtinCardFinishes,
+  cardDefinition,
+  cardMesh,
+  cardPose,
+  cardTiltCoordinates,
+  cardsPlugin,
+  createCardHit,
+  defineCardFinish,
+  hitCards,
+  prepareCardTextures,
+  sampleCardMotion
+};

package/dist/mesh.d.ts

@@ -0,0 +1,4 @@
+import { Mesh } from '@aethervtt/shard-mesh';
+import type { CardDefinitionValue } from './definition.js';
+/** True rounded geometry: picks, shadows and color share the same silhouette. */
+export declare function cardMesh(def: CardDefinitionValue, segments?: number): Mesh;

package/dist/mesh.js

@@ -0,0 +1,55 @@
+import { Mesh } from "@aethervtt/shard-mesh";
+function cardMesh(def, segments = 12) {
+  const w = def.size[0] / 2, h = def.size[1] / 2, r = def.cornerRadius;
+  const n = 4 * (segments + 1);
+  const ring = [];
+  for (let corner = 0; corner < 4; corner++) {
+    const cx = (corner === 0 || corner === 3 ? 1 : -1) * (w - r);
+    const cy = (corner < 2 ? 1 : -1) * (h - r);
+    for (let j = 0; j <= segments; j++) {
+      const a = (corner + j / segments) * Math.PI / 2;
+      ring.push(cx + Math.cos(a) * r, cy + Math.sin(a) * r);
+    }
+  }
+  const p = [], normals = [], uv = [], uv1 = [];
+  const indices = [];
+  const vertex = (x, y, z, nx, ny, nz, side) => {
+    const id = p.length / 3;
+    p.push(x, y, z);
+    normals.push(nx, ny, nz);
+    uv.push(side === 1 ? 0.5 - x / (2 * w) : x / (2 * w) + 0.5, 0.5 - y / (2 * h));
+    uv1.push(side, 0);
+    return id;
+  };
+  for (let side = 0; side < 2; side++) {
+    const z = (side === 0 ? 1 : -1) * def.thickness / 2;
+    const c = vertex(0, 0, z, 0, 0, side === 0 ? 1 : -1, side);
+    for (let i = 0; i < n; i++)
+      vertex(ring[i * 2], ring[i * 2 + 1], z, 0, 0, side === 0 ? 1 : -1, side);
+    for (let i = 0; i < n; i++) {
+      const a = c + 1 + i, b = c + 1 + (i + 1) % n;
+      indices.push(c, side === 0 ? a : b, side === 0 ? b : a);
+    }
+  }
+  if (def.thickness > 0)
+    for (let i = 0; i < n; i++) {
+      const j = (i + 1) % n;
+      const ax = ring[i * 2], ay = ring[i * 2 + 1], bx = ring[j * 2], by = ring[j * 2 + 1];
+      const dx = bx - ax, dy = by - ay, len = Math.sqrt(dx * dx + dy * dy) || 1;
+      const a = vertex(ax, ay, -def.thickness / 2, dy / len, -dx / len, 0, 2);
+      vertex(bx, by, -def.thickness / 2, dy / len, -dx / len, 0, 2);
+      vertex(bx, by, def.thickness / 2, dy / len, -dx / len, 0, 2);
+      vertex(ax, ay, def.thickness / 2, dy / len, -dx / len, 0, 2);
+      indices.push(a, a + 1, a + 2, a, a + 2, a + 3);
+    }
+  return Mesh.create({
+    positions: new Float32Array(p),
+    normals: new Float32Array(normals),
+    uvs: new Float32Array(uv),
+    uvs1: new Float32Array(uv1),
+    indices: new Uint16Array(indices)
+  });
+}
+export {
+  cardMesh
+};

package/dist/motion.d.ts

@@ -0,0 +1,12 @@
+import { type Infer } from '@aethervtt/shard-core';
+export declare const CardAutomaticMotion: import("@aethervtt/shard-core").ComponentDef<{
+    readonly enabled: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly tilt: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly seconds: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly range: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly phase: import("@aethervtt/shard-core").FieldType<number, "f32">;
+}>;
+export type CardAutomaticMotionValue = Infer<typeof CardAutomaticMotion>;
+/** Same integer waypoint generator and quintic interpolation as CARD_MOTION_WGSL. */
+export declare function sampleCardMotion(time: number, seconds: number, range: number, phase: number, out: Float32Array): void;
+export declare const CARD_MOTION_WGSL = "\nfn card_motion_point(step: u32) -> vec2f {\n  let x = ((step & 65535u) * 25173u + 13849u) & 65535u;\n  let y = (x * 25173u + 13849u) & 65535u;\n  return vec2f(f32(x), f32(y)) / 32767.5 - vec2f(1.0);\n}\nfn card_motion(time: f32, seconds: f32, radius: f32, phase: f32) -> vec2f {\n  let position = time / max(seconds, 0.25) + phase;\n  let step = u32(floor(position));\n  let t = fract(position);\n  let ease = t * t * t * (t * (t * 6.0 - 15.0) + 10.0);\n  return mix(card_motion_point(step), card_motion_point(step + 1u), ease) * radius;\n}\n";

package/dist/motion.js

@@ -0,0 +1,40 @@
+import { defineSchema, t } from "@aethervtt/shard-core";
+const CardAutomaticMotion = defineSchema("cards/AutomaticMotion", {
+  enabled: t.bool(),
+  tilt: t.bool(),
+  seconds: t.f32({ default: 4, min: 0.25, max: 60 }),
+  range: t.f32({ default: 0.85, min: 0, max: 1 }),
+  phase: t.f32({ min: 0, max: 1024 })
+});
+function sampleCardMotion(time, seconds, range, phase, out) {
+  const position = time / seconds + phase;
+  const step = Math.floor(position);
+  const t2 = position - step;
+  const ease = t2 * t2 * t2 * (t2 * (t2 * 6 - 15) + 10);
+  let a = Math.imul(step & 65535, 25173) + 13849 & 65535;
+  let b = Math.imul(step + 1 & 65535, 25173) + 13849 & 65535;
+  const ax = a / 32767.5 - 1, bx = b / 32767.5 - 1;
+  a = Math.imul(a, 25173) + 13849 & 65535;
+  b = Math.imul(b, 25173) + 13849 & 65535;
+  out[0] = (ax + (bx - ax) * ease) * range;
+  out[1] = (a / 32767.5 - 1 + (b - a) / 32767.5 * ease) * range;
+}
+const CARD_MOTION_WGSL = `
+fn card_motion_point(step: u32) -> vec2f {
+  let x = ((step & 65535u) * 25173u + 13849u) & 65535u;
+  let y = (x * 25173u + 13849u) & 65535u;
+  return vec2f(f32(x), f32(y)) / 32767.5 - vec2f(1.0);
+}
+fn card_motion(time: f32, seconds: f32, radius: f32, phase: f32) -> vec2f {
+  let position = time / max(seconds, 0.25) + phase;
+  let step = u32(floor(position));
+  let t = fract(position);
+  let ease = t * t * t * (t * (t * 6.0 - 15.0) + 10.0);
+  return mix(card_motion_point(step), card_motion_point(step + 1u), ease) * radius;
+}
+`;
+export {
+  CARD_MOTION_WGSL,
+  CardAutomaticMotion,
+  sampleCardMotion
+};

package/dist/plugin.d.ts

@@ -0,0 +1,13 @@
+import { type Plugin } from '@aethervtt/shard-runtime';
+import { type CardFinish } from './finishes.js';
+import type { CardTexturePage } from './textures.js';
+export interface CardsPluginOptions {
+    art: CardTexturePage;
+    masks: CardTexturePage;
+    /** Scene-lit PBR by default; unlit is an explicit presentation mode. */
+    lighting?: 'pbr' | 'unlit';
+    finishes?: readonly CardFinish[];
+    capacity?: number;
+    textureBudgetMiB?: number;
+}
+export declare function cardsPlugin(options: CardsPluginOptions): Plugin;