@terrafirmagreg-team/dump 0.0.0-stage → 1.2.1

package/src/lib/dump/assets/urls.ts

@@ -0,0 +1,145 @@
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import type {
+  AtlasPage,
+  IconAtlas,
+} from '@terrafirmagreg-team/dump/lib/dump/assets/atlas/dto';
+import {
+  cleanDumpRel,
+  dumpLocation,
+  dumpRelPublicUrl,
+  dumpStorageUrl,
+  splitDumpId,
+  type DumpLocation,
+} from '@terrafirmagreg-team/dump/lib/dump/paths';
+
+export { dumpRelPublicUrl } from '@terrafirmagreg-team/dump/lib/dump/paths';
+
+export function texturePublicUrl(
+  dataset: DatasetRef,
+  textureId: string,
+): string | undefined {
+  const parts = splitDumpId(textureId.trim());
+  if (!parts) return undefined;
+  const path = parts.path.startsWith('textures/')
+    ? parts.path
+    : `textures/${parts.path}`;
+  const rel = `${path.replace(/\.(png|webp)$/i, '')}.webp`;
+  return dumpRelPublicUrl(dataset, `assets/${parts.ns}/${rel}`);
+}
+
+export function modelPublicUrl(
+  dataset: DatasetRef,
+  namespace: string,
+  rel: string | null | undefined,
+): string | undefined {
+  const cleaned = typeof rel === 'string' ? cleanDumpRel(rel) : null;
+  return cleaned
+    ? dumpRelPublicUrl(dataset, `assets/${namespace}/${cleaned}`)
+    : undefined;
+}
+
+export function recipeImageUrl(
+  dataset: DatasetRef,
+  recipe: { modId: string; image?: string },
+): string | undefined {
+  const rel = recipe.image ? cleanDumpRel(recipe.image) : undefined;
+  if (!rel) return undefined;
+  if (rel.startsWith('assets/')) return dumpRelPublicUrl(dataset, rel);
+  if (!recipe.modId) return undefined;
+  return dumpRelPublicUrl(dataset, `assets/${recipe.modId}/${rel}`);
+}
+
+export function atlasPagePublicUrl(
+  dataset: DatasetRef,
+  atlas: IconAtlas,
+  page: AtlasPage,
+): string | undefined {
+  const src = cleanDumpRel(page.image);
+  if (!src || !atlas.modId) return undefined;
+  return dumpRelPublicUrl(dataset, `assets/${atlas.modId}/${src}`);
+}
+
+function pathDir(path: string): string {
+  const slash = path.lastIndexOf('/');
+  return slash >= 0 ? path.slice(0, slash + 1) : '';
+}
+
+function relativePath(fromDir: string, toPath: string): string {
+  const a = fromDir.split('/').filter(Boolean);
+  const b = toPath.split('/').filter(Boolean);
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) i += 1;
+  return '../'.repeat(a.length - i) + b.slice(i).join('/');
+}
+
+function resolveAssetRel(baseDir: string, relUri: string): string | null {
+  const out: string[] = [];
+  for (const seg of `${baseDir}${relUri}`.split('/')) {
+    if (seg === '..') {
+      if (!out.pop()) return null;
+    } else if (seg !== '.' && seg !== '') {
+      out.push(seg);
+    }
+  }
+  return out.length ? out.join('/') : null;
+}
+
+const reverseFileIndexes = new WeakMap<
+  Record<string, string>,
+  Map<string, string>
+>();
+function reverseFileIndex(files: Record<string, string>): Map<string, string> {
+  let map = reverseFileIndexes.get(files);
+  if (!map) {
+    map = new Map(Object.entries(files).map(([rel, key]) => [key, rel]));
+    reverseFileIndexes.set(files, map);
+  }
+  return map;
+}
+
+function dumpRelForStorageRel(
+  loc: DumpLocation,
+  storageRel: string,
+): string | undefined {
+  if (loc.files) return reverseFileIndex(loc.files).get(storageRel);
+  return storageRel.startsWith(`${loc.root}/`)
+    ? storageRel.slice(loc.root.length + 1)
+    : undefined;
+}
+
+export function createDumpAssetResolver(
+  dataset: DatasetRef,
+): (resourceUrl: string, modelUrl: string) => string | undefined {
+
+  let prefix: string | null = null;
+  return (resourceUrl, modelUrl) => {
+    const loc = dumpLocation(dataset);
+    if (!loc) return undefined;
+    const base =
+      typeof window === 'undefined' ? 'http://x.invalid' : location.origin;
+    prefix ??= new URL(dumpStorageUrl(''), base).href;
+    let resourcePath: string;
+    let modelAbs: URL;
+    try {
+      modelAbs = new URL(modelUrl, base);
+      const resource = new URL(resourceUrl, modelAbs);
+      if (resource.origin !== modelAbs.origin) return undefined;
+      resourcePath = resource.pathname;
+    } catch {
+      return undefined;
+    }
+    const modelHref = modelAbs.href;
+    if (!modelHref.startsWith(prefix)) return undefined;
+    const modelRel = dumpRelForStorageRel(
+      loc,
+      modelHref.slice(prefix.length),
+    );
+    if (!modelRel) return undefined;
+    const rel = relativePath(pathDir(modelAbs.pathname), resourcePath);
+    if (!rel || !rel.includes('/')) return undefined;
+    const dumpRel = resolveAssetRel(pathDir(modelRel), rel);
+    if (!dumpRel) return undefined;
+    return dumpRelPublicUrl(dataset, dumpRel);
+  };
+}
+

package/src/lib/dump/client/atlases.ts

@@ -0,0 +1,85 @@
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import type { AtlasBundle, IconAtlas } from '@terrafirmagreg-team/dump/lib/dump/assets/atlas/dto';
+import {
+  iconAtlasFromEntries,
+  mergeAtlases,
+} from '@terrafirmagreg-team/dump/lib/dump/assets/atlas/sprites';
+import {
+  clientDumpJson,
+  loadClientManifest,
+} from '@terrafirmagreg-team/dump/lib/dump/client/dump';
+import { asRecord } from '@terrafirmagreg-team/dump/lib/dump/contract/read';
+import { createDatasetCache } from '@terrafirmagreg-team/dump/lib/dump/reader';
+
+async function modEntries(
+  dataset: DatasetRef,
+  modId: string,
+  kind: string,
+): Promise<Record<string, unknown> | undefined> {
+  const entries = asRecord(
+    await clientDumpJson(dataset, `registry/${kind}.json`, 'high'),
+  );
+  if (!entries) return undefined;
+  const prefix = `${modId}:`;
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(entries)) {
+    if (key.startsWith(prefix)) out[key] = value;
+  }
+  return out;
+}
+
+const loadClientModAtlas = createDatasetCache(
+  async (
+    dataset: DatasetRef,
+    modId: string,
+    kind: 'items' | 'blocks',
+  ): Promise<IconAtlas | null> => {
+    const manifest = await loadClientManifest(dataset);
+    const listed = manifest?.namespaces[modId];
+    if (!listed) return null;
+    const has = (file: string) => listed.registry.includes(file);
+    if (kind === 'blocks') {
+      if (!has('blocks')) return null;
+      return iconAtlasFromEntries(
+        await modEntries(dataset, modId, 'blocks'),
+        dataset,
+        modId,
+        'blocks',
+        'block',
+      );
+    }
+    return mergeAtlases(
+      [
+        has('items')
+          ? iconAtlasFromEntries(
+              await modEntries(dataset, modId, 'items'),
+              dataset,
+              modId,
+              'items',
+              'item',
+            )
+          : null,
+        has('fluids')
+          ? iconAtlasFromEntries(
+              await modEntries(dataset, modId, 'fluids'),
+              dataset,
+              modId,
+              'fluids',
+              'item',
+            )
+          : null,
+      ],
+      dataset,
+      modId,
+      'item',
+    );
+  },
+);
+
+export const loadClientModAtlases = createDatasetCache(
+  async (dataset: DatasetRef, modId: string): Promise<AtlasBundle> => ({
+    items: await loadClientModAtlas(dataset, modId, 'items'),
+    blocks: await loadClientModAtlas(dataset, modId, 'blocks'),
+  }),
+);
+

package/src/lib/dump/client/dump.ts

@@ -0,0 +1,132 @@
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import { dumpReader } from '@terrafirmagreg-team/dump/lib/dump/reader';
+import { DUMP_POINTER_TTL } from '@terrafirmagreg-team/dump/lib/dump/json-reader';
+import { dumpRelPublicUrl, splitDumpId } from '@terrafirmagreg-team/dump/lib/dump/paths';
+import { stackIdBase } from '@terrafirmagreg-team/dump/lib/dump/contract/ref';
+import { asRecord } from '@terrafirmagreg-team/dump/lib/dump/contract/read';
+import {
+  modelPublicUrl,
+  texturePublicUrl,
+} from '@terrafirmagreg-team/dump/lib/dump/assets/urls';
+import { createAsyncCache } from '@terrafirmagreg-team/data/lib/async-cache';
+import { loadDatasetDump } from '@terrafirmagreg-team/dump/lib/dump/mods/load';
+import {
+  dumpModRegistryRel,
+  dumpRegistryRel,
+} from '@terrafirmagreg-team/dump/lib/dump/mods/index';
+import type { DumpManifest } from '@terrafirmagreg-team/dump/lib/dump/manifest/dto';
+
+export function loadClientManifest(
+  dataset: DatasetRef,
+): Promise<DumpManifest | null> {
+  return loadDatasetDump(dataset).then((dump) => dump?.manifest ?? null);
+}
+
+export type DatasetVersions = { latest?: string; versions: string[] };
+
+export const loadClientVersions = createAsyncCache(
+  async (datasetId: string): Promise<DatasetVersions | null> => {
+    const reader = await dumpReader({ id: datasetId });
+    const raw = await reader.getJson('versions.json');
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+    const row = raw as Record<string, unknown>;
+    const versions = Array.isArray(row.versions)
+      ? row.versions.filter((v): v is string => typeof v === 'string')
+      : [];
+    if (!versions.length) return null;
+    return {
+      latest: typeof row.latest === 'string' ? row.latest : undefined,
+      versions,
+    };
+  },
+  undefined,
+  DUMP_POINTER_TTL,
+);
+
+export function clientDumpJson(
+  dataset: DatasetRef,
+  rel: string | null | undefined,
+  priority?: 'high',
+): Promise<unknown | undefined> {
+  if (!rel) return Promise.resolve(undefined);
+  return dumpReader(dataset).then((reader) => reader.getJson(rel, priority));
+}
+
+export async function clientRegistryEntries(
+  dataset: DatasetRef,
+  file: string,
+  priority?: 'high',
+): Promise<Record<string, unknown> | undefined> {
+  const rel = dumpRegistryRel(await loadDatasetDump(dataset), file);
+  return rel
+    ? asRecord(await clientDumpJson(dataset, rel, priority))
+    : undefined;
+}
+
+export function clientDumpLang(
+  dataset: DatasetRef,
+  lang: string,
+): Promise<Record<string, string>> {
+  return dumpReader(dataset).then((reader) => reader.getLang(lang));
+}
+
+export function clientDumpLangRaw(
+  dataset: DatasetRef,
+  lang: string,
+): Promise<Record<string, string>> {
+  return dumpReader(dataset).then((reader) => reader.getLangRaw(lang));
+}
+
+export async function clientRegistryDataFileRel(
+  dataset: DatasetRef,
+  ns: string,
+  file: string,
+): Promise<string | undefined> {
+  return dumpModRegistryRel(await loadDatasetDump(dataset), ns, file);
+}
+
+function stackNs(id: string): string | undefined {
+  const ns = stackIdBase(id).split(':', 1)[0];
+  return ns || undefined;
+}
+
+export function clientTagFileRel(
+  dataset: DatasetRef,
+  tagId: string,
+): Promise<string | undefined> {
+  const ns = stackNs(tagId.startsWith('#') ? tagId.slice(1) : tagId);
+  return ns
+    ? clientRegistryDataFileRel(dataset, ns, 'tags')
+    : Promise.resolve(undefined);
+}
+
+export function dumpTextureUrl(
+  dataset: DatasetRef,
+  textureId: string,
+): string | undefined {
+  return texturePublicUrl(dataset, textureId);
+}
+
+export async function dumpModelUrl(
+  dataset: DatasetRef,
+  modelId: string,
+): Promise<string | undefined> {
+  const parts = splitDumpId(modelId.trim());
+  if (!parts) return undefined;
+  const index = await clientDumpJson(
+    dataset,
+    `data/${parts.ns}/models/multiblock.json`,
+  );
+  const rel =
+    index && typeof index === 'object' && !Array.isArray(index)
+      ? (index as Record<string, unknown>)[modelId]
+      : undefined;
+  return modelPublicUrl(
+    dataset,
+    parts.ns,
+    typeof rel === 'string' ? rel : undefined,
+  );
+}
+
+export { dumpRelPublicUrl };
+

package/src/lib/dump/client/groups.ts

@@ -0,0 +1,27 @@
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import { asRecord, asStringList } from '@terrafirmagreg-team/dump/lib/dump/contract/read';
+import { asDumpText, type DumpText } from '@terrafirmagreg-team/dump/lib/dump/contract/text';
+import { clientRegistryEntries } from '@terrafirmagreg-team/dump/lib/dump/client/dump';
+import { createDatasetCache } from '@terrafirmagreg-team/dump/lib/dump/reader';
+
+type RegistryGroupRow = {
+  id: string;
+  name?: DumpText;
+  members: string[];
+};
+
+export const loadClientRegistryGroups = createDatasetCache(
+  async (dataset: DatasetRef): Promise<RegistryGroupRow[]> => {
+    const out: RegistryGroupRow[] = [];
+    const entries = await clientRegistryEntries(dataset, 'groups');
+    for (const [id, raw] of Object.entries(entries ?? {})) {
+      const row = asRecord(raw);
+      const members = asStringList(row?.members);
+      if (!id || members.length <= 1) continue;
+      const name = asDumpText(row?.name);
+      out.push({ id, ...(name ? { name } : {}), members });
+    }
+    return out;
+  },
+);
+

package/src/lib/dump/client/keybinds.ts

@@ -0,0 +1,16 @@
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import { asStringMap } from '@terrafirmagreg-team/dump/lib/dump/contract/read';
+import { clientDumpJson } from '@terrafirmagreg-team/dump/lib/dump/client/dump';
+import { loadDatasetDump } from '@terrafirmagreg-team/dump/lib/dump/mods/load';
+import { createDatasetCache } from '@terrafirmagreg-team/dump/lib/dump/reader';
+
+export const loadClientKeybinds = createDatasetCache(
+  async (dataset: DatasetRef): Promise<Record<string, string>> => {
+    const dump = await loadDatasetDump(dataset);
+    const file = dump?.mods.find((mod) => mod.keybindsFile)?.keybindsFile;
+    return file
+      ? (asStringMap(await clientDumpJson(dataset, file, 'high')) ?? {})
+      : {};
+  },
+);
+

package/src/lib/dump/client/mods.ts

@@ -0,0 +1,18 @@
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import { langString } from '@terrafirmagreg-team/dump/lib/dump/assets/lang/names';
+import { clientDumpLang, loadClientManifest } from '@terrafirmagreg-team/dump/lib/dump/client/dump';
+import { createDatasetCache } from '@terrafirmagreg-team/dump/lib/dump/reader';
+
+export const loadClientModNames = createDatasetCache(
+  async (dataset: DatasetRef, lang: string): Promise<Record<string, string>> => {
+    const manifest = await loadClientManifest(dataset);
+    const map = await clientDumpLang(dataset, lang);
+    const out: Record<string, string> = {};
+    for (const [ns, entry] of Object.entries(manifest?.namespaces ?? {})) {
+      const key = entry?.display?.name;
+      out[ns] = langString(map, key) ?? key ?? ns;
+    }
+    return out;
+  },
+);
+

package/src/lib/dump/client/registry.ts

@@ -0,0 +1,121 @@
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import { asIdTable, EDGE_TABLE_FIELD } from '@terrafirmagreg-team/dump/lib/dump/contract/read';
+import { asEntry, displayOf } from '@terrafirmagreg-team/dump/lib/dump/data/registry/parse';
+import { parseStackId } from '@terrafirmagreg-team/dump/lib/dump/contract/ref';
+import type { DumpDisplay, DumpText } from '@terrafirmagreg-team/dump/lib/dump/contract/text';
+import type {
+  DumpBlockEntry,
+  DumpEntityEntry,
+  DumpFluidEntry,
+  DumpItemEntry,
+  DumpRegistryEntry,
+  DumpRegistryKind,
+} from '@terrafirmagreg-team/dump/lib/dump/data/registry/dto';
+import { clientRegistryEntries } from '@terrafirmagreg-team/dump/lib/dump/client/dump';
+import { createDatasetCache } from '@terrafirmagreg-team/dump/lib/dump/reader';
+
+type RegistryByKind = {
+  items: DumpItemEntry;
+  blocks: DumpBlockEntry;
+  fluids: DumpFluidEntry;
+  entities: DumpEntityEntry;
+};
+
+const KIND_FILE: Record<DumpRegistryKind, string> = {
+  items: 'items',
+  blocks: 'blocks',
+  fluids: 'fluids',
+  entities: 'entities',
+};
+
+const clientRegistry = createDatasetCache(
+  async (
+    dataset: DatasetRef,
+    kind: DumpRegistryKind,
+  ): Promise<Map<string, DumpRegistryEntry>> => {
+    const out = new Map<string, DumpRegistryEntry>();
+    const file = KIND_FILE[kind];
+    const entries = await clientRegistryEntries(dataset, file);
+    const ids = asIdTable(entries);
+    for (const [id, raw] of Object.entries(entries ?? {})) {
+      if (id === EDGE_TABLE_FIELD) continue;
+      const entry = asEntry(raw, kind, id, ids);
+      if (!entry) continue;
+      if (!out.has(id)) out.set(id, entry);
+      if (entry.id !== id && !out.has(entry.id)) {
+        out.set(entry.id, entry);
+      }
+    }
+    return out;
+  },
+);
+
+export function loadClientRegistry<K extends DumpRegistryKind>(
+  dataset: DatasetRef,
+  kind: K,
+): Promise<Map<string, RegistryByKind[K]>> {
+  return clientRegistry(dataset, kind) as Promise<Map<string, RegistryByKind[K]>>;
+}
+
+export function resolveClientStackDisplay(
+  compactId: string,
+  items: Map<string, DumpItemEntry>,
+  fluids: Map<string, DumpFluidEntry>,
+): DumpDisplay | undefined {
+  const parsed = parseStackId(compactId);
+  const item = items.get(parsed.id);
+  if (item) return displayOf(item, parsed.nbt);
+  const fluid = fluids.get(parsed.id);
+  if (fluid) return displayOf(fluid, parsed.nbt);
+  return undefined;
+}
+
+const SINGULAR_KIND: Record<string, DumpRegistryKind> = {
+  item: 'items',
+  block: 'blocks',
+  fluid: 'fluids',
+  entity: 'entities',
+};
+
+export function clientRegistryKindFor(kind: string): DumpRegistryKind {
+  return SINGULAR_KIND[kind] ?? (kind as DumpRegistryKind);
+}
+
+export async function loadClientRegistryOrder(
+  dataset: DatasetRef,
+  kind: string,
+): Promise<string[]> {
+  const entries = await loadClientRegistry(dataset, clientRegistryKindFor(kind));
+  return [...entries.values()]
+    .flatMap((entry) => (entry.order != null ? [entry] : []))
+    .sort((a, b) => (a.order ?? 0) - (b.order ?? 0) || a.id.localeCompare(b.id))
+    .map((entry) => entry.id);
+}
+
+export async function loadClientRegistryTooltips(
+  dataset: DatasetRef,
+  kind: string,
+): Promise<Record<string, DumpText[]> | undefined> {
+  const entries = await loadClientRegistry(dataset, clientRegistryKindFor(kind));
+  const out: Record<string, DumpText[]> = {};
+  for (const entry of entries.values()) {
+    const tooltip = entry.display?.tooltip;
+    if (tooltip?.length) out[entry.id] = tooltip;
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
+export async function loadClientRegistryTooltipsMod(
+  dataset: DatasetRef,
+  kind: string,
+  mod: string,
+): Promise<Record<string, DumpText[]> | undefined> {
+  const entries = await loadClientRegistry(dataset, clientRegistryKindFor(kind));
+  const out: Record<string, DumpText[]> = {};
+  for (const entry of entries.values()) {
+    const lines = entry.display?.tooltipMods?.[mod];
+    if (lines?.length) out[entry.id] = lines;
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+

package/src/lib/dump/client/tabs.ts

@@ -0,0 +1,23 @@
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import { asTab, asTabItems } from '@terrafirmagreg-team/dump/lib/dump/data/tab/parse';
+import type { DumpCreativeTab, DumpCreativeTabs } from '@terrafirmagreg-team/dump/lib/dump/data/tab/dto';
+import { clientRegistryEntries } from '@terrafirmagreg-team/dump/lib/dump/client/dump';
+import { createDatasetCache } from '@terrafirmagreg-team/dump/lib/dump/reader';
+
+export const loadClientTabs = createDatasetCache(
+  async (dataset: DatasetRef): Promise<DumpCreativeTabs> => {
+    const tabs: DumpCreativeTab[] = [];
+    const members: Record<string, string[]> = {};
+    const entries = await clientRegistryEntries(dataset, 'tabs');
+    for (const raw of Object.values(entries ?? {})) {
+      const tab = asTab(raw);
+      if (!tab) continue;
+      tabs.push(tab);
+      const items = asTabItems(raw);
+      if (items.length) members[tab.id] = items;
+    }
+    tabs.sort((a, b) => a.order - b.order || a.id.localeCompare(b.id));
+    return { tabs, members };
+  },
+);
+

package/src/lib/dump/client/tags.ts

@@ -0,0 +1,59 @@
+import type { DatasetRef } from '@terrafirmagreg-team/sites/location';
+import { asIdTable, EDGE_TABLE_FIELD } from '@terrafirmagreg-team/dump/lib/dump/contract/read';
+import { asTag } from '@terrafirmagreg-team/dump/lib/dump/data/tag/parse';
+import type { DumpTag } from '@terrafirmagreg-team/dump/lib/dump/data/tag/dto';
+import { clientRegistryEntries } from '@terrafirmagreg-team/dump/lib/dump/client/dump';
+import { tagHashId, tagIdForms } from '@terrafirmagreg-team/dump/lib/dump/paths';
+import { createDatasetCache } from '@terrafirmagreg-team/dump/lib/dump/reader';
+
+function indexKeys(tag: DumpTag, manifestKey: string): string[] {
+  return [...new Set([manifestKey, ...tagIdForms(tag.id)])];
+}
+
+const loadClientTags = createDatasetCache(async (dataset: DatasetRef) => {
+  const map = new Map<string, DumpTag>();
+  const entries = await clientRegistryEntries(dataset, 'tags');
+  const ids = asIdTable(entries);
+  for (const [manifestKey, raw] of Object.entries(entries ?? {})) {
+    if (manifestKey === EDGE_TABLE_FIELD) continue;
+    const tag = asTag(raw, manifestKey, ids);
+    if (!tag) continue;
+    for (const alias of indexKeys(tag, manifestKey)) {
+      if (!map.has(alias)) map.set(alias, tag);
+    }
+  }
+  return map;
+});
+
+export async function resolveClientTag(
+  dataset: DatasetRef,
+  id: string,
+): Promise<DumpTag | undefined> {
+  const tags = await loadClientTags(dataset);
+  for (const form of tagIdForms(id)) {
+    const hit = tags.get(form);
+    if (hit) return hit;
+  }
+  return undefined;
+}
+
+const MEMBER_REGISTRY: Record<string, string> = {
+  item: 'items',
+  block: 'blocks',
+  fluid: 'fluids',
+  entity: 'entities',
+};
+
+export async function loadClientTagMembers(
+  dataset: DatasetRef,
+  kind: string,
+): Promise<Record<string, string[]> | undefined> {
+  const registry = MEMBER_REGISTRY[kind] ?? kind;
+  const out: Record<string, string[]> = {};
+  for (const tag of (await loadClientTags(dataset)).values()) {
+    if (tag.registry !== registry || !tag.members.length) continue;
+    out[tagHashId(tag.id)] ??= tag.members;
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+

package/src/lib/dump/contract/kind.ts

@@ -0,0 +1,62 @@
+import {
+  asTaggedReference,
+  stackIdFromRef,
+  type ReferenceKind,
+  type TaggedReference,
+} from '@terrafirmagreg-team/dump/lib/dump/contract/ref';
+import { asRecord, asString } from '@terrafirmagreg-team/dump/lib/dump/contract/read';
+
+const LINK_KINDS = [
+  'item',
+  'block',
+  'fluid',
+  'entity',
+  'tag',
+  'texture',
+  'recipe',
+  'quest',
+  'guide',
+] as const;
+
+export type ResourceKind = (typeof LINK_KINDS)[number];
+
+export function asResourceKind(value: unknown): ResourceKind | undefined {
+  return typeof value === 'string' &&
+    (LINK_KINDS as readonly string[]).includes(value)
+    ? (value as ResourceKind)
+    : undefined;
+}
+
+export function referenceKindFromResource(
+  kind: ResourceKind | undefined,
+): ReferenceKind | undefined {
+  switch (kind) {
+    case 'tag':
+      return 'itemTag';
+    case 'item':
+    case 'block':
+    case 'fluid':
+    case 'entity':
+    case 'texture':
+    case 'recipe':
+    case 'quest':
+    case 'guide':
+      return kind;
+    default:
+      return undefined;
+  }
+}
+
+export function referenceFrom(value: unknown): TaggedReference | undefined {
+  const tagged = asTaggedReference(value);
+  if (tagged) return { kind: tagged.kind, id: stackIdFromRef(tagged) };
+  const row = asRecord(value);
+  const tagId = asString(row?.tag);
+  if (tagId && row?.id === undefined && row?.kind === undefined) {
+    return { kind: 'itemTag', id: `#${tagId}` };
+  }
+  const kind = referenceKindFromResource(asResourceKind(row?.kind));
+  const id = asString(row?.id);
+  return kind && id ? { kind, id } : undefined;
+}
+