@digitalcanopy/assets 1.0.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +55 -0
- package/dist/catalog/index.d.mts +94 -0
- package/dist/catalog/index.d.ts +94 -0
- package/dist/catalog/index.js +540 -0
- package/dist/catalog/index.mjs +30 -0
- package/dist/chunk-BUUV7WRE.mjs +502 -0
- package/dist/chunk-CIMJYYCP.mjs +3612 -0
- package/dist/chunk-FECYZWQ6.mjs +278 -0
- package/dist/chunk-MFWLT2XV.mjs +47 -0
- package/dist/index.d.mts +5 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.js +4483 -0
- package/dist/index.mjs +74 -0
- package/dist/manifests/index.d.mts +79 -0
- package/dist/manifests/index.d.ts +79 -0
- package/dist/manifests/index.js +3647 -0
- package/dist/manifests/index.mjs +24 -0
- package/dist/registry/index.d.mts +98 -0
- package/dist/registry/index.d.ts +98 -0
- package/dist/registry/index.js +321 -0
- package/dist/registry/index.mjs +12 -0
- package/dist/resolvers/cdn.d.mts +16 -0
- package/dist/resolvers/cdn.d.ts +16 -0
- package/dist/resolvers/cdn.js +76 -0
- package/dist/resolvers/cdn.mjs +16 -0
- package/dist/types-Cy3PZIX4.d.mts +52 -0
- package/dist/types-_dmvJ9qx.d.ts +52 -0
- package/package.json +19 -3
- package/scripts/generate-manifests.mjs +0 -409
- package/src/__tests__/manifests.test.ts +0 -129
- package/src/__tests__/resolvers.test.ts +0 -83
- package/src/__tests__/sync-r2.test.ts +0 -82
- package/src/index.ts +0 -2
- package/src/manifests/index.ts +0 -81
- package/src/manifests/isometric-tiles.atlas.json +0 -592
- package/src/manifests/keys.ts +0 -160
- package/src/manifests/modular-characters.atlas.json +0 -856
- package/src/manifests/playing-cards.atlas.json +0 -1408
- package/src/manifests/ui-sprites.atlas.json +0 -568
- package/src/resolvers/cdn.ts +0 -52
- package/src/resolvers/index.ts +0 -1
- package/tsconfig.build.json +0 -12
- package/tsconfig.json +0 -20
package/README.md
CHANGED
|
@@ -25,9 +25,13 @@ yarn add @digitalcanopy/assets
|
|
|
25
25
|
- `uiSpritesAtlas`: 23 UI elements (buttons, panels, icons, progress bars).
|
|
26
26
|
- **Flame Coordinate Converter**: `toFlameSpriteData(manifest, frameKey)` converts manifest entries directly into `[srcPosition, srcSize, anchor]` tuples for Flutter Flame `SpriteComponent.fromFrame`.
|
|
27
27
|
- **Strict TypeScript Keys**: Exported constant arrays and union types (`PLAYING_CARDS`, `ISOMETRIC_TILES`, `MODULAR_CHARACTERS`, `UI_SPRITES`) for IDE autocomplete.
|
|
28
|
+
- **Database Catalog Schema & Ingestion**: Direct integration with PostgreSQL `catalog.assets` table via `@digitalcanopy/assets/catalog`, complete with canonical seed assets and query loaders.
|
|
29
|
+
- **Dynamic Hot-Swapping Registry**: Drop-in custom IP hot-swapping at runtime via `@digitalcanopy/assets/registry` (`AssetRegistry`, `assetRegistry`), supporting pack overrides, single-key overrides, custom Flame frames/anchors, reactive pub/sub event streams, and graceful fallback to baseline Kenney assets.
|
|
28
30
|
|
|
29
31
|
## Usage
|
|
30
32
|
|
|
33
|
+
### 1. Canonical CDN Resolvers & Atlas Manifests
|
|
34
|
+
|
|
31
35
|
```typescript
|
|
32
36
|
import {
|
|
33
37
|
getKenneyCardUrl,
|
|
@@ -44,3 +48,54 @@ const cardUrl = getKenneyCardUrl('card-spades-10');
|
|
|
44
48
|
const spriteData = toFlameSpriteData(playingCardsAtlas, 'card-spades-a');
|
|
45
49
|
// => { srcPosition: [0, 0], srcSize: [140, 190], anchor: [0.5, 0.5] }
|
|
46
50
|
```
|
|
51
|
+
|
|
52
|
+
### 2. Drop-In Custom IP Hot-Swapping
|
|
53
|
+
|
|
54
|
+
```typescript
|
|
55
|
+
import {
|
|
56
|
+
assetRegistry,
|
|
57
|
+
playingCardsAtlas,
|
|
58
|
+
} from '@digitalcanopy/assets';
|
|
59
|
+
|
|
60
|
+
// Hot-swap an entire pack with a custom IP theme
|
|
61
|
+
assetRegistry.registerPackOverride('cards', 'https://cdn.digitalcanopy.io/custom-ip/cyberpunk-cards');
|
|
62
|
+
|
|
63
|
+
// Hot-swap a single legendary asset with custom high-DPI frame and anchor point
|
|
64
|
+
assetRegistry.registerOverride('card-spades-a', {
|
|
65
|
+
url: 'https://cdn.digitalcanopy.io/custom-ip/cyberpunk-cards/holo_ace.svg',
|
|
66
|
+
frame: { x: 0, y: 0, w: 280, h: 380 },
|
|
67
|
+
anchor: { ax: 0.5, ay: 0.5 },
|
|
68
|
+
});
|
|
69
|
+
|
|
70
|
+
// Resolves to custom IP URL automatically
|
|
71
|
+
const cardUrl = assetRegistry.resolveCardUrl('card-spades-a');
|
|
72
|
+
// => "https://cdn.digitalcanopy.io/custom-ip/cyberpunk-cards/holo_ace.svg"
|
|
73
|
+
|
|
74
|
+
// Unmodified cards resolve under the custom pack override
|
|
75
|
+
const kingUrl = assetRegistry.resolveCardUrl('card-hearts-k');
|
|
76
|
+
// => "https://cdn.digitalcanopy.io/custom-ip/cyberpunk-cards/card-hearts-k.png"
|
|
77
|
+
|
|
78
|
+
// Flame engine sprite coordinates dynamically adapt to the custom IP frame
|
|
79
|
+
const flameData = assetRegistry.resolveFlameSpriteData(playingCardsAtlas, 'card-spades-a');
|
|
80
|
+
// => { srcPosition: [0, 0], srcSize: [280, 380], anchor: [0.5, 0.5] }
|
|
81
|
+
|
|
82
|
+
// Subscribe to real-time hot-swap events to trigger reactive re-renders
|
|
83
|
+
const unsubscribe = assetRegistry.onSwap((event) => {
|
|
84
|
+
console.log('Assets hot-swapped:', event.type, event.keys);
|
|
85
|
+
});
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
### 3. Database Catalog Integration (`catalog.assets`)
|
|
89
|
+
|
|
90
|
+
```typescript
|
|
91
|
+
import { loadCatalogAssets, assetRegistry } from '@digitalcanopy/assets';
|
|
92
|
+
|
|
93
|
+
// Load catalog assets scoped to War: Second Wind (WSW) from PostgreSQL or fallback cache
|
|
94
|
+
const wswAssets = await loadCatalogAssets({
|
|
95
|
+
app_scope: 'wsw',
|
|
96
|
+
fallbackToSeed: true,
|
|
97
|
+
});
|
|
98
|
+
|
|
99
|
+
// Ingest catalog directly into the active hot-swapping registry
|
|
100
|
+
assetRegistry.loadCatalog(wswAssets);
|
|
101
|
+
```
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
import { a as CatalogAsset } from '../types-Cy3PZIX4.mjs';
|
|
2
|
+
export { C as CatalogAppScope, b as CatalogAssetInsert, c as CatalogAssetMetadata, d as CatalogAssetRow, e as CatalogAssetUpdate, f as CatalogCategory } from '../types-Cy3PZIX4.mjs';
|
|
3
|
+
import '../manifests/index.mjs';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Canonical seed dataset from PostgreSQL migration 20261010110001_kenney_asset_catalog.sql.
|
|
7
|
+
* Used for in-memory resolution, offline testing, and initial cache hydration.
|
|
8
|
+
*/
|
|
9
|
+
declare const SEED_CATALOG_ASSETS: readonly CatalogAsset[];
|
|
10
|
+
|
|
11
|
+
declare const CATALOG_SCHEMA_NAME = "catalog";
|
|
12
|
+
declare const CATALOG_TABLE_NAME = "assets";
|
|
13
|
+
declare const CATALOG_FULL_TABLE_NAME = "catalog.assets";
|
|
14
|
+
/**
|
|
15
|
+
* Full PostgreSQL DDL specification for catalog.assets.
|
|
16
|
+
* Matches sunshade-db-platform migration 20261010110001_kenney_asset_catalog.sql.
|
|
17
|
+
*/
|
|
18
|
+
declare const CATALOG_ASSETS_SCHEMA_SQL: string;
|
|
19
|
+
/**
|
|
20
|
+
* Type guard to check if an unknown object conforms to the CatalogAsset interface.
|
|
21
|
+
*/
|
|
22
|
+
declare function isCatalogAsset(value: unknown): value is CatalogAsset;
|
|
23
|
+
/**
|
|
24
|
+
* Detailed validator returning human-readable validation errors.
|
|
25
|
+
*/
|
|
26
|
+
declare function validateCatalogAsset(asset: unknown): {
|
|
27
|
+
valid: boolean;
|
|
28
|
+
errors: string[];
|
|
29
|
+
};
|
|
30
|
+
/**
|
|
31
|
+
* Generates a normalized asset key slug from parts.
|
|
32
|
+
*/
|
|
33
|
+
declare function formatCatalogAssetKey(appScope: string, category: string, identifier: string): string;
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Minimal duck-typed interface matching Supabase PostgREST client queries.
|
|
37
|
+
*/
|
|
38
|
+
interface SupabaseClientLike {
|
|
39
|
+
schema?: (schemaName: string) => SupabaseClientLike;
|
|
40
|
+
from: (table: string) => {
|
|
41
|
+
select: (columns?: string) => any;
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
interface CatalogQueryOptions {
|
|
45
|
+
/**
|
|
46
|
+
* Filter by one or more app scopes (e.g. 'avatar-studio', 'wsw', 'all').
|
|
47
|
+
*/
|
|
48
|
+
app_scope?: string | string[];
|
|
49
|
+
/**
|
|
50
|
+
* Filter by one or more asset categories (e.g. 'card_face', 'avatar_hair').
|
|
51
|
+
*/
|
|
52
|
+
category?: string | string[];
|
|
53
|
+
/**
|
|
54
|
+
* Filter by explicit asset keys.
|
|
55
|
+
*/
|
|
56
|
+
asset_keys?: string[];
|
|
57
|
+
/**
|
|
58
|
+
* Optional active Supabase client instance.
|
|
59
|
+
* If omitted, the loader falls back to canonical SEED_CATALOG_ASSETS.
|
|
60
|
+
*/
|
|
61
|
+
supabaseClient?: SupabaseClientLike;
|
|
62
|
+
/**
|
|
63
|
+
* Whether to fall back to in-memory SEED_CATALOG_ASSETS if the remote query fails or returns empty.
|
|
64
|
+
* Default: true.
|
|
65
|
+
*/
|
|
66
|
+
fallbackToSeed?: boolean;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* Filters an array of catalog assets in memory according to the specified criteria.
|
|
70
|
+
*/
|
|
71
|
+
declare function filterCatalog(assets: readonly CatalogAsset[], filter: {
|
|
72
|
+
app_scope?: string | string[];
|
|
73
|
+
category?: string | string[];
|
|
74
|
+
asset_keys?: string[];
|
|
75
|
+
}): CatalogAsset[];
|
|
76
|
+
/**
|
|
77
|
+
* Filters catalog assets strictly by app_scope.
|
|
78
|
+
*/
|
|
79
|
+
declare function filterCatalogByScope(assets: readonly CatalogAsset[], appScope: string): CatalogAsset[];
|
|
80
|
+
/**
|
|
81
|
+
* Filters catalog assets strictly by category.
|
|
82
|
+
*/
|
|
83
|
+
declare function filterCatalogByCategory(assets: readonly CatalogAsset[], category: string): CatalogAsset[];
|
|
84
|
+
/**
|
|
85
|
+
* Indexes an array of catalog assets into a Map keyed by asset_key.
|
|
86
|
+
*/
|
|
87
|
+
declare function createCatalogMap(assets: readonly CatalogAsset[]): Map<string, CatalogAsset>;
|
|
88
|
+
/**
|
|
89
|
+
* Asynchronously loads catalog assets from Supabase PostgreSQL (catalog.assets table)
|
|
90
|
+
* or falls back to in-memory canonical seed assets.
|
|
91
|
+
*/
|
|
92
|
+
declare function loadCatalogAssets(options?: CatalogQueryOptions): Promise<CatalogAsset[]>;
|
|
93
|
+
|
|
94
|
+
export { CATALOG_ASSETS_SCHEMA_SQL, CATALOG_FULL_TABLE_NAME, CATALOG_SCHEMA_NAME, CATALOG_TABLE_NAME, CatalogAsset, type CatalogQueryOptions, SEED_CATALOG_ASSETS, type SupabaseClientLike, createCatalogMap, filterCatalog, filterCatalogByCategory, filterCatalogByScope, formatCatalogAssetKey, isCatalogAsset, loadCatalogAssets, validateCatalogAsset };
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
import { a as CatalogAsset } from '../types-_dmvJ9qx.js';
|
|
2
|
+
export { C as CatalogAppScope, b as CatalogAssetInsert, c as CatalogAssetMetadata, d as CatalogAssetRow, e as CatalogAssetUpdate, f as CatalogCategory } from '../types-_dmvJ9qx.js';
|
|
3
|
+
import '../manifests/index.js';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Canonical seed dataset from PostgreSQL migration 20261010110001_kenney_asset_catalog.sql.
|
|
7
|
+
* Used for in-memory resolution, offline testing, and initial cache hydration.
|
|
8
|
+
*/
|
|
9
|
+
declare const SEED_CATALOG_ASSETS: readonly CatalogAsset[];
|
|
10
|
+
|
|
11
|
+
declare const CATALOG_SCHEMA_NAME = "catalog";
|
|
12
|
+
declare const CATALOG_TABLE_NAME = "assets";
|
|
13
|
+
declare const CATALOG_FULL_TABLE_NAME = "catalog.assets";
|
|
14
|
+
/**
|
|
15
|
+
* Full PostgreSQL DDL specification for catalog.assets.
|
|
16
|
+
* Matches sunshade-db-platform migration 20261010110001_kenney_asset_catalog.sql.
|
|
17
|
+
*/
|
|
18
|
+
declare const CATALOG_ASSETS_SCHEMA_SQL: string;
|
|
19
|
+
/**
|
|
20
|
+
* Type guard to check if an unknown object conforms to the CatalogAsset interface.
|
|
21
|
+
*/
|
|
22
|
+
declare function isCatalogAsset(value: unknown): value is CatalogAsset;
|
|
23
|
+
/**
|
|
24
|
+
* Detailed validator returning human-readable validation errors.
|
|
25
|
+
*/
|
|
26
|
+
declare function validateCatalogAsset(asset: unknown): {
|
|
27
|
+
valid: boolean;
|
|
28
|
+
errors: string[];
|
|
29
|
+
};
|
|
30
|
+
/**
|
|
31
|
+
* Generates a normalized asset key slug from parts.
|
|
32
|
+
*/
|
|
33
|
+
declare function formatCatalogAssetKey(appScope: string, category: string, identifier: string): string;
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Minimal duck-typed interface matching Supabase PostgREST client queries.
|
|
37
|
+
*/
|
|
38
|
+
interface SupabaseClientLike {
|
|
39
|
+
schema?: (schemaName: string) => SupabaseClientLike;
|
|
40
|
+
from: (table: string) => {
|
|
41
|
+
select: (columns?: string) => any;
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
interface CatalogQueryOptions {
|
|
45
|
+
/**
|
|
46
|
+
* Filter by one or more app scopes (e.g. 'avatar-studio', 'wsw', 'all').
|
|
47
|
+
*/
|
|
48
|
+
app_scope?: string | string[];
|
|
49
|
+
/**
|
|
50
|
+
* Filter by one or more asset categories (e.g. 'card_face', 'avatar_hair').
|
|
51
|
+
*/
|
|
52
|
+
category?: string | string[];
|
|
53
|
+
/**
|
|
54
|
+
* Filter by explicit asset keys.
|
|
55
|
+
*/
|
|
56
|
+
asset_keys?: string[];
|
|
57
|
+
/**
|
|
58
|
+
* Optional active Supabase client instance.
|
|
59
|
+
* If omitted, the loader falls back to canonical SEED_CATALOG_ASSETS.
|
|
60
|
+
*/
|
|
61
|
+
supabaseClient?: SupabaseClientLike;
|
|
62
|
+
/**
|
|
63
|
+
* Whether to fall back to in-memory SEED_CATALOG_ASSETS if the remote query fails or returns empty.
|
|
64
|
+
* Default: true.
|
|
65
|
+
*/
|
|
66
|
+
fallbackToSeed?: boolean;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* Filters an array of catalog assets in memory according to the specified criteria.
|
|
70
|
+
*/
|
|
71
|
+
declare function filterCatalog(assets: readonly CatalogAsset[], filter: {
|
|
72
|
+
app_scope?: string | string[];
|
|
73
|
+
category?: string | string[];
|
|
74
|
+
asset_keys?: string[];
|
|
75
|
+
}): CatalogAsset[];
|
|
76
|
+
/**
|
|
77
|
+
* Filters catalog assets strictly by app_scope.
|
|
78
|
+
*/
|
|
79
|
+
declare function filterCatalogByScope(assets: readonly CatalogAsset[], appScope: string): CatalogAsset[];
|
|
80
|
+
/**
|
|
81
|
+
* Filters catalog assets strictly by category.
|
|
82
|
+
*/
|
|
83
|
+
declare function filterCatalogByCategory(assets: readonly CatalogAsset[], category: string): CatalogAsset[];
|
|
84
|
+
/**
|
|
85
|
+
* Indexes an array of catalog assets into a Map keyed by asset_key.
|
|
86
|
+
*/
|
|
87
|
+
declare function createCatalogMap(assets: readonly CatalogAsset[]): Map<string, CatalogAsset>;
|
|
88
|
+
/**
|
|
89
|
+
* Asynchronously loads catalog assets from Supabase PostgreSQL (catalog.assets table)
|
|
90
|
+
* or falls back to in-memory canonical seed assets.
|
|
91
|
+
*/
|
|
92
|
+
declare function loadCatalogAssets(options?: CatalogQueryOptions): Promise<CatalogAsset[]>;
|
|
93
|
+
|
|
94
|
+
export { CATALOG_ASSETS_SCHEMA_SQL, CATALOG_FULL_TABLE_NAME, CATALOG_SCHEMA_NAME, CATALOG_TABLE_NAME, CatalogAsset, type CatalogQueryOptions, SEED_CATALOG_ASSETS, type SupabaseClientLike, createCatalogMap, filterCatalog, filterCatalogByCategory, filterCatalogByScope, formatCatalogAssetKey, isCatalogAsset, loadCatalogAssets, validateCatalogAsset };
|