@alizarin/napi 0.2.1-alpha.85 → 2.0.0-alpha.100

package/Cargo.toml

@@ -16,6 +16,7 @@ napi = { version = "2", features = ["napi6", "serde-json"] }
 napi-derive = "2"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
+uuid = { version = "1", features = ["v4", "v5"] }
 
 [build-dependencies]
 napi-build = "2"

package/__test__/index.mjs

@@ -4,7 +4,7 @@ import path from 'node:path';
 import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
-import { NapiStaticGraph, NapiStaticResourceRegistry, NapiResourceModelWrapper, NapiResourceInstanceWrapper } from '../index.js';
+import { NapiStaticGraph, NapiStaticResourceRegistry, NapiResourceModelWrapper, NapiResourceInstanceWrapper, NapiNodeConfigManager } from '../index.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const TEST_DATA = path.resolve(__dirname, '..', '..', '..', 'tests');
@@ -345,7 +345,7 @@ describe('NapiPseudoValue property names', () => {
 
   // Create instance wrapper and load tiles
   const instanceWrapper = new NapiResourceInstanceWrapper(resource.resourceinstance.graph_id);
-  instanceWrapper.loadTilesFromResource(resource);
+  instanceWrapper.loadTilesFromResource(JSON.stringify(resource));
 
   // Get a PseudoList and PseudoValue
   const pseudoList = instanceWrapper.getValuesAtPath('basic_info.name');
@@ -433,13 +433,13 @@ describe('NapiResourceInstanceWrapper methods', () => {
 
   it('has setTileDataForNode method', () => {
     const wrapper = new NapiResourceInstanceWrapper(graphId);
-    wrapper.loadTilesFromResource(resource);
+    wrapper.loadTilesFromResource(JSON.stringify(resource));
     assert.equal(typeof wrapper.setTileDataForNode, 'function');
   });
 
   it('setTileDataForNode mutates tile data', () => {
     const wrapper = new NapiResourceInstanceWrapper(graphId);
-    wrapper.loadTilesFromResource(resource);
+    wrapper.loadTilesFromResource(JSON.stringify(resource));
 
     const tileIds = wrapper.getAllTileIds();
     assert.ok(tileIds.length > 0, 'should have tiles');
@@ -459,13 +459,13 @@ describe('NapiResourceInstanceWrapper methods', () => {
     assert.equal(typeof wrapper.tilesLoaded, 'function');
     assert.equal(wrapper.tilesLoaded(), false);
 
-    wrapper.loadTilesFromResource(resource);
+    wrapper.loadTilesFromResource(JSON.stringify(resource));
     assert.equal(wrapper.tilesLoaded(), true);
   });
 
   it('has toJson method', () => {
     const wrapper = new NapiResourceInstanceWrapper(graphId);
-    wrapper.loadTilesFromResource(resource);
+    wrapper.loadTilesFromResource(JSON.stringify(resource));
     assert.equal(typeof wrapper.toJson, 'function');
     // toJson requires populate() first; just verify the method exists
     // and that calling it without populate gives a meaningful error
@@ -481,7 +481,7 @@ describe('NapiResourceInstanceWrapper methods', () => {
 
   it('exportTilesJson returns valid JSON array of tiles', () => {
     const wrapper = new NapiResourceInstanceWrapper(graphId);
-    wrapper.loadTilesFromResource(resource);
+    wrapper.loadTilesFromResource(JSON.stringify(resource));
 
     const json = wrapper.exportTilesJson();
     assert.equal(typeof json, 'string');
@@ -499,7 +499,7 @@ describe('NapiResourceInstanceWrapper methods', () => {
 
   it('exportTilesJson reflects setTileDataForNode mutations', () => {
     const wrapper = new NapiResourceInstanceWrapper(graphId);
-    wrapper.loadTilesFromResource(resource);
+    wrapper.loadTilesFromResource(JSON.stringify(resource));
 
     const tileIds = wrapper.getAllTileIds();
     const tileId = tileIds[0];
@@ -522,3 +522,83 @@ describe('NapiResourceInstanceWrapper methods', () => {
     assert.equal(tiles.length, 0, 'should be empty');
   });
 });
+
+// =============================================================================
+// NapiNodeConfigManager + NapiStaticGraph integration
+// Regression: loadFromGraph used JSON.stringify on a NapiStaticGraph, which
+// produced {} because NAPI class getters are not enumerable own properties.
+// The fix uses buildFromGraph (direct struct reference) instead.
+// =============================================================================
+
+describe('NapiNodeConfigManager', () => {
+  const personJson = fs.readFileSync(
+    path.join(TEST_DATA, 'data', 'models', 'Person.json'),
+    'utf-8'
+  );
+
+  it('buildFromGraph accepts a NapiStaticGraph without error', () => {
+    const graph = NapiStaticGraph.fromJsonString(personJson);
+    const ncm = new NapiNodeConfigManager();
+    // This is the path that failed when using JSON.stringify(napiGraph)
+    ncm.buildFromGraph(graph);
+  });
+
+  it('buildFromGraphJson fails on JSON.stringify of a NapiStaticGraph', () => {
+    const graph = NapiStaticGraph.fromJsonString(personJson);
+    const ncm = new NapiNodeConfigManager();
+    // Demonstrates the bug: NAPI objects don't stringify their getters
+    const stringified = JSON.stringify(graph);
+    assert.throws(
+      () => ncm.buildFromGraphJson(stringified),
+      /Failed to parse graph/i,
+      'JSON.stringify of NapiStaticGraph should produce invalid graph JSON'
+    );
+  });
+
+  it('buildFromGraphJson works with raw graph JSON', () => {
+    const parsed = JSON.parse(personJson);
+    const graphObj = parsed.graph ? parsed.graph[0] : parsed;
+    const ncm = new NapiNodeConfigManager();
+    // Raw JS object stringifies correctly
+    ncm.buildFromGraphJson(JSON.stringify(graphObj));
+  });
+});
+
+// =============================================================================
+// NapiStaticGraph serialization guard
+// Regression: JSON.stringify(NapiStaticGraph) produces {} because NAPI class
+// getters are not enumerable own properties. Any code path that does
+// JSON.stringify(graph) where graph could be a NapiStaticGraph will break.
+// =============================================================================
+
+describe('NapiStaticGraph serialization', () => {
+  const groupJson = fs.readFileSync(
+    path.join(TEST_DATA, 'data', 'models', 'Group.json'),
+    'utf-8'
+  );
+
+  it('JSON.stringify of NapiStaticGraph produces empty object', () => {
+    const graph = NapiStaticGraph.fromJsonString(groupJson);
+    const stringified = JSON.stringify(graph);
+    // This documents the fundamental limitation: NAPI class instances
+    // do not serialize via JSON.stringify
+    assert.equal(stringified, '{}', 'NapiStaticGraph should stringify to {}');
+  });
+
+  it('NapiResourceModelWrapper.fromGraph accepts NapiStaticGraph directly', () => {
+    const graph = NapiStaticGraph.fromJsonString(groupJson);
+    // This is the correct NAPI path — no JSON.stringify needed
+    const wrapper = NapiResourceModelWrapper.fromGraph(graph, true);
+    assert.equal(wrapper.getGraphId(), '07883c9e-b25c-11e9-975a-a4d18cec433a');
+  });
+
+  it('NapiResourceModelWrapper constructor fails with JSON.stringify of NapiStaticGraph', () => {
+    const graph = NapiStaticGraph.fromJsonString(groupJson);
+    // Demonstrates the bug this regression test guards against
+    assert.throws(
+      () => new NapiResourceModelWrapper(JSON.stringify(graph), true),
+      /Invalid graph JSON/i,
+      'JSON.stringify of NapiStaticGraph should produce invalid input for constructor'
+    );
+  });
+});

package/index.d.ts

@@ -17,7 +17,7 @@ export declare function buildGraphFromCsvs(graphCsv: string, nodesCsv: string, c
  * Returns the resources wrapped in the `{ business_data: { resources: [...] } }`
  * format expected by PrebuildLoader.
  */
-export declare function buildBusinessDataFromCsv(csvData: string, graphJson: string, collectionsJson: string): any
+export declare function buildBusinessDataFromCsv(csvData: string, graphJson: string, collectionsJson: string, defaultLanguage?: string | undefined | null, strictConcepts?: boolean | undefined | null): any
 /**
  * Coerce a value using the registered extension handler for the given datatype.
  *
@@ -40,6 +40,32 @@ export declare function extensionResolveMarkers(datatype: string, tileData: any,
 export declare function hasExtensionHandler(datatype: string): boolean
 /** List all registered extension handler datatypes. */
 export declare function getRegisteredExtensionHandlers(): Array<string>
+/** Parse SKOS RDF/XML and return all collections as a JSON array. */
+export declare function parseSkosXml(xmlContent: string, baseUri: string): any
+/** Parse SKOS RDF/XML and return a single collection (the first one found). */
+export declare function parseSkosXmlToCollection(xmlContent: string, baseUri: string): any
+/** Serialize a single SkosCollection to SKOS RDF/XML. */
+export declare function collectionToSkosXml(collectionJson: any, baseUri: string): string
+/** Serialize multiple SkosCollections to SKOS RDF/XML. */
+export declare function collectionsToSkosXml(collectionsJson: any, baseUri: string): string
+/**
+ * Build a mapping from node alias to collection ID based on graph definition.
+ *
+ * Equivalent to WASM's `buildAliasToCollectionMap`.
+ */
+export declare function buildAliasToCollectionMap(graphJson: string, resolvableDatatypes?: Array<string> | undefined | null, configKeys?: Array<string> | undefined | null): Record<string, string>
+/**
+ * Scan a JSON tree to find which collections are needed for resolution.
+ *
+ * Equivalent to WASM's `findNeededCollections`.
+ */
+export declare function findNeededCollections(treeJson: string, aliasToCollection: Record<string, string>): Array<string>
+/** Check if a string is a valid UUID. */
+export declare function isValidUuid(s: string): boolean
+/** Get the default resolvable datatypes (concept, concept-list). */
+export declare function getDefaultResolvableDatatypes(): Array<string>
+/** Get the default config keys for collection IDs. */
+export declare function getDefaultConfigKeys(): Array<string>
 /**
  * Import a prebuild/pkg directory: register graphs, load SKOS collections,
  * and load ontology configs.
@@ -58,6 +84,18 @@ export declare class NapiRdmCache {
   /** Load a single collection from JSON. */
   loadCollectionJson(jsonStr: string): void
   get collectionCount(): number
+  /** Check if a collection is already in the cache. */
+  hasCollection(collectionId: string): boolean
+  /** Add a collection from a JSON string of concepts. */
+  addCollectionFromJson(collectionId: string, jsonStr: string): void
+  /** Get the parent concept ID for a concept within a collection. */
+  getParentId(collectionId: string, conceptId: string): string | null
+  /** Remove a collection from the cache. */
+  removeCollection(collectionId: string): boolean
+  /** Clear all collections from the cache. */
+  clear(): void
+  /** Resolve labels to UUIDs using this cache for lookups. */
+  resolveLabels(treeJson: string, aliasToCollection: Record<string, string>, strict: boolean): any
 }
 export declare class NapiNodeConfigManager {
   constructor()
@@ -66,6 +104,33 @@ export declare class NapiNodeConfigManager {
   /** Build node configs from a NapiStaticGraph. */
   buildFromGraph(graph: NapiStaticGraph): void
 }
+export declare class NapiTileData {
+  has(key: string): boolean
+  get(key: string): any
+  set(key: string, value: any): void
+  delete(key: string): boolean
+  keys(): Array<string>
+}
+export declare class NapiStaticTile {
+  constructor(nodegroupId: string, tileid?: string | undefined | null, sortorder?: number | undefined | null, resourceinstanceId?: string | undefined | null, parenttileId?: string | undefined | null)
+  get data(): NapiTileData
+  /**
+   * Setter is a no-op — data is always accessed via the NapiTileData getter.
+   * Exists to prevent TypeError in strict mode when JS does
+   * `tile.data = tile.data || new Map()`.
+   */
+  set data(value: any)
+  get tileid(): string | null
+  set tileid(value?: string | undefined | null)
+  get nodegroupId(): string
+  get sortorder(): number | null
+  get resourceinstanceId(): string
+  get parenttileId(): string | null
+  set parenttileId(value?: string | undefined | null)
+  get provisionaledits(): any
+  /** Generate a tile ID if not already set. */
+  ensureId(): string
+}
 export declare class NapiPseudoValue {
   get node(): any
   get nodeId(): string | null
@@ -96,6 +161,12 @@ export declare class NapiPseudoValue {
   toSnapshot(): any
   /** Clear tile data */
   clear(): void
+  get tile(): NapiStaticTile | null
+  set tile(tile?: NapiStaticTile | undefined | null)
+  /** Get the inner PseudoValueCore wrapped as NapiPseudoValue. */
+  get inner(): NapiPseudoValue | null
+  /** Returns null — value is managed JS-side via _cachedValue. */
+  get value(): any
 }
 export declare class NapiPseudoList {
   get nodeAlias(): string
@@ -126,12 +197,22 @@ export declare class NapiValuesFromNodegroupResult {
   get impliedNodegroups(): Array<string>
 }
 export declare class NapiResourceInstanceWrapper {
-  /** Create a wrapper for a given graph (must be registered). */
-  constructor(graphId: string)
-  /** Load tiles from a JSON array. */
-  loadTiles(tilesJs: any): void
-  /** Load tiles directly from a StaticResource JSON. */
-  loadTilesFromResource(resourceJs: any): void
+  /**
+   * Create a wrapper for a given graph (must be registered).
+   *
+   * If `resource_id` is provided, a minimal resource metadata is created so
+   * the tile-source fast path can look up tiles by resource.
+   */
+  constructor(graphId: string, resourceId?: string | undefined | null)
+  /** Load tiles from a JSON string (single-pass deserialization). */
+  loadTiles(tilesJson: string): void
+  /** Load tiles directly from a StaticResource JSON string (single-pass deserialization). */
+  loadTilesFromResource(resourceJson: string): void
+  /**
+   * Load tiles directly from a NapiStaticResourceRegistry by resource ID.
+   * This avoids the JS round-trip of serializing tiles to JS and back.
+   */
+  loadFromRegistry(resourceId: string, registry: NapiStaticResourceRegistry): boolean
   /** Append tiles incrementally (for lazy loading). */
   appendTiles(tilesJs: any): void
   getTileCount(): number
@@ -169,6 +250,13 @@ export declare class NapiResourceInstanceWrapper {
   ensureNodegroup(allValuesJs: any, allNodegroupsJs: any, nodegroupId: string, addIfMissing: boolean, nodegroupPermissionsJs: any, doImpliedNodegroups: boolean): NapiEnsureNodegroupResult
   /** Build pseudo values from tiles for a specific nodegroup. */
   valuesFromResourceNodegroup(existingValuesJs: any, nodegroupTileIds: Array<string>, nodegroupId: string): NapiValuesFromNodegroupResult
+  /**
+   * Resolve a dot-separated path to its target node metadata without needing tiles.
+   *
+   * Returns { nodegroupId, isSingle, targetNodeId } — enough for the JS layer to
+   * lazy-load just that nodegroup's tiles before calling getValuesAtPath.
+   */
+  resolvePath(path: string): any
   /** Resolve a dot-separated path and return a PseudoList. */
   getValuesAtPath(path: string): NapiPseudoList
   /**
@@ -289,6 +377,13 @@ export declare class NapiStaticGraph {
   get name(): any
   /** Register this graph in the global registry so NapiResourceInstanceWrapper can use it. */
   register(): void
+  /**
+   * Set a descriptor template for computing resource name/description/slug.
+   *
+   * Template placeholders use `<Node Name>` syntax, e.g. `"<Headword>"`.
+   * Descriptor types: "name", "description", "slug".
+   */
+  setDescriptorTemplate(descriptorType: string, stringTemplate: string): void
 }
 export declare class NapiStaticResourceRegistry {
   constructor()
@@ -305,7 +400,7 @@ export declare class NapiStaticResourceRegistry {
   /** Insert full resources from a business_data JSON file string. */
   mergeFromBusinessDataJson(businessDataJson: string, storeFull?: boolean | undefined | null): void
   /** Build an inverted index: visibility value -> [resource IDs]. */
-  getValueToResourcesIndex(graph: NapiStaticGraph, nodeIdentifier: string, flattenLocalized?: boolean | undefined | null): Record<string, Array<string>>
+  getValueToResourcesIndex(graph: NapiStaticGraph, nodeIdentifier: string, flattenLocalized?: boolean | undefined | null, rdmCache?: NapiRdmCache | undefined | null): Record<string, Array<string>>
   /**
    * Extract values from one node in tiles where another node matches a filter.
    *
@@ -323,4 +418,21 @@ export declare class NapiStaticResourceRegistry {
   getFull(resourceId: string): any | null
   /** Get a summary for a resource (works for both summary and full entries), or null if unknown. */
   getSummary(resourceId: string): any | null
+  /** Get diagnostic stats about registry contents (entry counts, tile counts, etc.) */
+  memoryStats(): any
+  /** Get detailed stats including estimated byte sizes (expensive — re-serializes all data) */
+  memoryStatsDetailed(): any
+  /**
+   * Populate __cache on resources with summaries for referenced resources.
+   *
+   * Uses the graph to identify resource-instance nodes, then populates
+   * cache entries for each referenced resource found in this registry.
+   *
+   * If `enrich_relationships` is true, also adds ontologyProperty to tile data.
+   * If `recompute_descriptors` is true, recomputes resource name/description from
+   * descriptor templates set on the graph.
+   *
+   * Returns `{ resources, unknownReferences, hasUnknown }`.
+   */
+  populateCachesFromJson(resourcesJson: string, graph: NapiStaticGraph, enrichRelationships?: boolean | undefined | null, strict?: boolean | undefined | null, recomputeDescriptors?: boolean | undefined | null): any
 }

package/index.js

@@ -310,10 +310,12 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { NapiRdmCache, NapiNodeConfigManager, NapiPseudoValue, NapiPseudoList, NapiPopulateResult, NapiEnsureNodegroupResult, NapiValuesFromNodegroupResult, NapiResourceInstanceWrapper, NapiResourceModelWrapper, NapiPrebuildExporter, NapiStaticGraph, NapiStaticResourceRegistry, buildGraphFromCsvs, buildBusinessDataFromCsv, extensionCoerce, extensionRenderDisplay, extensionResolveMarkers, hasExtensionHandler, getRegisteredExtensionHandlers, importPrebuild } = nativeBinding
+const { NapiRdmCache, NapiNodeConfigManager, NapiTileData, NapiStaticTile, NapiPseudoValue, NapiPseudoList, NapiPopulateResult, NapiEnsureNodegroupResult, NapiValuesFromNodegroupResult, NapiResourceInstanceWrapper, NapiResourceModelWrapper, NapiPrebuildExporter, NapiStaticGraph, NapiStaticResourceRegistry, buildGraphFromCsvs, buildBusinessDataFromCsv, extensionCoerce, extensionRenderDisplay, extensionResolveMarkers, hasExtensionHandler, getRegisteredExtensionHandlers, parseSkosXml, parseSkosXmlToCollection, collectionToSkosXml, collectionsToSkosXml, buildAliasToCollectionMap, findNeededCollections, isValidUuid, getDefaultResolvableDatatypes, getDefaultConfigKeys, importPrebuild } = nativeBinding
 
 module.exports.NapiRdmCache = NapiRdmCache
 module.exports.NapiNodeConfigManager = NapiNodeConfigManager
+module.exports.NapiTileData = NapiTileData
+module.exports.NapiStaticTile = NapiStaticTile
 module.exports.NapiPseudoValue = NapiPseudoValue
 module.exports.NapiPseudoList = NapiPseudoList
 module.exports.NapiPopulateResult = NapiPopulateResult
@@ -331,4 +333,13 @@ module.exports.extensionRenderDisplay = extensionRenderDisplay
 module.exports.extensionResolveMarkers = extensionResolveMarkers
 module.exports.hasExtensionHandler = hasExtensionHandler
 module.exports.getRegisteredExtensionHandlers = getRegisteredExtensionHandlers
+module.exports.parseSkosXml = parseSkosXml
+module.exports.parseSkosXmlToCollection = parseSkosXmlToCollection
+module.exports.collectionToSkosXml = collectionToSkosXml
+module.exports.collectionsToSkosXml = collectionsToSkosXml
+module.exports.buildAliasToCollectionMap = buildAliasToCollectionMap
+module.exports.findNeededCollections = findNeededCollections
+module.exports.isValidUuid = isValidUuid
+module.exports.getDefaultResolvableDatatypes = getDefaultResolvableDatatypes
+module.exports.getDefaultConfigKeys = getDefaultConfigKeys
 module.exports.importPrebuild = importPrebuild

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alizarin/napi",
-  "version": "0.2.1-alpha.85",
+  "version": "2.0.0-alpha.100",
   "license": "AGPL-3.0-or-later",
   "repository": {
     "type": "git",
@@ -30,8 +30,8 @@
     "@napi-rs/cli": "^2.18.0"
   },
   "optionalDependencies": {
-    "@alizarin/napi-win32-x64-msvc": "0.2.1-alpha.85",
-    "@alizarin/napi-darwin-x64": "0.2.1-alpha.85",
-    "@alizarin/napi-linux-x64-gnu": "0.2.1-alpha.85"
+    "@alizarin/napi-win32-x64-msvc": "2.0.0-alpha.100",
+    "@alizarin/napi-darwin-x64": "2.0.0-alpha.100",
+    "@alizarin/napi-linux-x64-gnu": "2.0.0-alpha.100"
   }
 }

package/src/instance_wrapper_napi.rs

@@ -4,7 +4,7 @@
 /// the TypeScript ViewModel layer (ResourceInstanceWrapper / PseudoValue / PseudoList)
 /// can work with either backend.
 use std::collections::HashMap;
-use std::sync::Arc;
+use std::sync::{Arc, Mutex};
 
 use napi::bindgen_prelude::*;
 use napi_derive::napi;
@@ -44,7 +44,14 @@ fn sc_err(e: SemanticChildError) -> napi::Error {
 
 #[napi]
 pub struct NapiRdmCache {
-    inner: RdmCache,
+    pub(crate) inner: RdmCache,
+}
+
+impl NapiRdmCache {
+    /// Crate-internal accessor (field not directly accessible through #[napi] macro).
+    pub(crate) fn inner(&self) -> &RdmCache {
+        &self.inner
+    }
 }
 
 #[napi]
@@ -82,6 +89,64 @@ impl NapiRdmCache {
     pub fn collection_count(&self) -> u32 {
         self.inner.len() as u32
     }
+
+    /// Check if a collection is already in the cache.
+    #[napi]
+    pub fn has_collection(&self, collection_id: String) -> bool {
+        self.inner.has_collection(&collection_id)
+    }
+
+    /// Add a collection from a JSON string of concepts.
+    #[napi]
+    pub fn add_collection_from_json(
+        &mut self,
+        collection_id: String,
+        json_str: String,
+    ) -> Result<()> {
+        self.inner
+            .add_collection_from_json(&collection_id, &json_str)
+            .map_err(|e| napi::Error::from_reason(format!("Failed to add collection: {e}")))
+    }
+
+    /// Get the parent concept ID for a concept within a collection.
+    #[napi]
+    pub fn get_parent_id(&self, collection_id: String, concept_id: String) -> Option<String> {
+        self.inner.get_parent_id(&collection_id, &concept_id)
+    }
+
+    /// Remove a collection from the cache.
+    #[napi]
+    pub fn remove_collection(&mut self, collection_id: String) -> bool {
+        self.inner.remove_collection(&collection_id)
+    }
+
+    /// Clear all collections from the cache.
+    #[napi]
+    pub fn clear(&mut self) {
+        self.inner.clear();
+    }
+
+    /// Resolve labels to UUIDs using this cache for lookups.
+    #[napi]
+    pub fn resolve_labels(
+        &self,
+        tree_json: String,
+        alias_to_collection: HashMap<String, String>,
+        strict: bool,
+    ) -> Result<serde_json::Value> {
+        let tree: serde_json::Value = serde_json::from_str(&tree_json)
+            .map_err(|e| napi::Error::from_reason(format!("Invalid tree JSON: {e}")))?;
+
+        let resolved = alizarin_core::label_resolution::resolve_labels(
+            tree,
+            &alias_to_collection,
+            &self.inner,
+            strict,
+        )
+        .map_err(|e| napi::Error::from_reason(e.message))?;
+
+        Ok(resolved)
+    }
 }
 
 // =============================================================================
@@ -118,6 +183,181 @@ impl NapiNodeConfigManager {
     }
 }
 
+// =============================================================================
+// NapiTileData — Map-like interface over HashMap<String, Value>
+// =============================================================================
+
+#[napi]
+pub struct NapiTileData {
+    entries: Arc<Mutex<HashMap<String, serde_json::Value>>>,
+}
+
+#[napi]
+impl NapiTileData {
+    #[napi]
+    pub fn has(&self, key: String) -> bool {
+        self.entries.lock().unwrap().contains_key(&key)
+    }
+
+    #[napi]
+    pub fn get(&self, key: String) -> serde_json::Value {
+        self.entries
+            .lock()
+            .unwrap()
+            .get(&key)
+            .cloned()
+            .unwrap_or(serde_json::Value::Null)
+    }
+
+    #[napi]
+    pub fn set(&mut self, key: String, value: serde_json::Value) {
+        self.entries.lock().unwrap().insert(key, value);
+    }
+
+    #[napi]
+    pub fn delete(&mut self, key: String) -> bool {
+        self.entries.lock().unwrap().remove(&key).is_some()
+    }
+
+    #[napi]
+    pub fn keys(&self) -> Vec<String> {
+        self.entries.lock().unwrap().keys().cloned().collect()
+    }
+}
+
+// =============================================================================
+// NapiStaticTile — Rust-owned tile with Map-like .data access
+// =============================================================================
+
+#[napi]
+pub struct NapiStaticTile {
+    tileid: Option<String>,
+    nodegroup_id: String,
+    sortorder: Option<i32>,
+    resourceinstance_id: String,
+    parenttile_id: Option<String>,
+    provisionaledits: Option<Vec<serde_json::Value>>,
+    data_store: Arc<Mutex<HashMap<String, serde_json::Value>>>,
+}
+
+#[napi]
+impl NapiStaticTile {
+    #[napi(constructor)]
+    pub fn new(
+        nodegroup_id: String,
+        tileid: Option<String>,
+        sortorder: Option<i32>,
+        resourceinstance_id: Option<String>,
+        parenttile_id: Option<String>,
+    ) -> Self {
+        NapiStaticTile {
+            tileid,
+            nodegroup_id,
+            sortorder,
+            resourceinstance_id: resourceinstance_id.unwrap_or_default(),
+            parenttile_id,
+            provisionaledits: None,
+            data_store: Arc::new(Mutex::new(HashMap::new())),
+        }
+    }
+
+    #[napi(getter)]
+    pub fn data(&self) -> NapiTileData {
+        NapiTileData {
+            entries: self.data_store.clone(),
+        }
+    }
+
+    /// Setter is a no-op — data is always accessed via the NapiTileData getter.
+    /// Exists to prevent TypeError in strict mode when JS does
+    /// `tile.data = tile.data || new Map()`.
+    #[napi(setter)]
+    pub fn set_data(&mut self, _value: serde_json::Value) {
+        // No-op: mutations go through NapiTileData.set/delete
+    }
+
+    #[napi(getter)]
+    pub fn tileid(&self) -> Option<String> {
+        self.tileid.clone()
+    }
+
+    #[napi(setter)]
+    pub fn set_tileid(&mut self, value: Option<String>) {
+        self.tileid = value;
+    }
+
+    #[napi(getter)]
+    pub fn nodegroup_id(&self) -> String {
+        self.nodegroup_id.clone()
+    }
+
+    #[napi(getter)]
+    pub fn sortorder(&self) -> Option<i32> {
+        self.sortorder
+    }
+
+    #[napi(getter)]
+    pub fn resourceinstance_id(&self) -> String {
+        self.resourceinstance_id.clone()
+    }
+
+    #[napi(getter)]
+    pub fn parenttile_id(&self) -> Option<String> {
+        self.parenttile_id.clone()
+    }
+
+    #[napi(setter)]
+    pub fn set_parenttile_id(&mut self, value: Option<String>) {
+        self.parenttile_id = value;
+    }
+
+    #[napi(getter)]
+    pub fn provisionaledits(&self) -> serde_json::Value {
+        match &self.provisionaledits {
+            Some(edits) => serde_json::to_value(edits).unwrap_or(serde_json::Value::Null),
+            None => serde_json::Value::Null,
+        }
+    }
+
+    /// Generate a tile ID if not already set.
+    #[napi(js_name = "ensureId")]
+    pub fn ensure_id(&mut self) -> String {
+        if self.tileid.is_none() {
+            self.tileid = Some(uuid::Uuid::new_v4().to_string());
+        }
+        self.tileid.clone().unwrap()
+    }
+}
+
+impl NapiStaticTile {
+    /// Convert to core StaticTile for storage in PseudoValueCore.
+    pub(crate) fn to_static_tile(&self) -> StaticTile {
+        let data = self.data_store.lock().unwrap().clone();
+        StaticTile {
+            tileid: self.tileid.clone(),
+            nodegroup_id: self.nodegroup_id.clone(),
+            sortorder: self.sortorder,
+            resourceinstance_id: self.resourceinstance_id.clone(),
+            parenttile_id: self.parenttile_id.clone(),
+            provisionaledits: self.provisionaledits.clone(),
+            data,
+        }
+    }
+
+    /// Create from a core StaticTile.
+    pub(crate) fn from_static_tile(tile: &StaticTile) -> Self {
+        NapiStaticTile {
+            tileid: tile.tileid.clone(),
+            nodegroup_id: tile.nodegroup_id.clone(),
+            sortorder: tile.sortorder,
+            resourceinstance_id: tile.resourceinstance_id.clone(),
+            parenttile_id: tile.parenttile_id.clone(),
+            provisionaledits: tile.provisionaledits.clone(),
+            data_store: Arc::new(Mutex::new(tile.data.clone())),
+        }
+    }
+}
+
 // =============================================================================
 // NapiPseudoValue
 // =============================================================================
@@ -269,15 +509,17 @@ impl NapiPseudoValue {
     pub fn to_snapshot(&self) -> serde_json::Value {
         serde_json::json!({
             "nodeId": self.inner.node.nodeid,
+            "name": &self.inner.node.name,
             "alias": self.inner.node.alias,
             "datatype": &self.inner.node.datatype,
             "nodegroupId": self.inner.node.nodegroup_id,
+            "sortorder": self.inner.node.sortorder,
+            "isOuter": self.inner.is_outer(),
+            "isInner": self.inner.is_inner,
             "isCollector": self.inner.is_collector,
+            "accessed": false,
             "independent": self.inner.independent,
-            "exportable": self.inner.node.exportable,
-            "isrequired": self.inner.node.isrequired,
-            "issearchable": self.inner.node.issearchable,
-            "hascustomalias": self.inner.node.hascustomalias,
+            "hasTile": self.inner.tile.is_some(),
             "tileId": self.inner.tile.as_ref().and_then(|t| t.tileid.clone()),
             "tileData": &self.inner.tile_data,
             "valueLoaded": self.inner.tile.is_some(),
@@ -290,6 +532,45 @@ impl NapiPseudoValue {
     pub fn clear(&mut self) {
         self.inner.tile_data = None;
     }
+
+    // -- Tile getter/setter (NapiStaticTile, Rust-owned) --
+
+    #[napi(getter, js_name = "tile")]
+    pub fn get_tile(&self) -> Option<NapiStaticTile> {
+        self.inner
+            .tile
+            .as_ref()
+            .map(|t| NapiStaticTile::from_static_tile(t.as_ref()))
+    }
+
+    #[napi(setter, js_name = "tile")]
+    pub fn set_tile(&mut self, tile: Option<&NapiStaticTile>) {
+        match tile {
+            Some(t) => {
+                self.inner.tile = Some(Arc::new(t.to_static_tile()));
+            }
+            None => {
+                self.inner.tile = None;
+            }
+        }
+    }
+
+    // -- Inner (outer/inner pattern) --
+
+    /// Get the inner PseudoValueCore wrapped as NapiPseudoValue.
+    #[napi(getter)]
+    pub fn inner(&self) -> Option<NapiPseudoValue> {
+        self.inner
+            .inner
+            .as_ref()
+            .map(|i| NapiPseudoValue { inner: *i.clone() })
+    }
+
+    /// Returns null — value is managed JS-side via _cachedValue.
+    #[napi(getter)]
+    pub fn value(&self) -> serde_json::Value {
+        serde_json::Value::Null
+    }
 }
 
 // =============================================================================
@@ -506,8 +787,11 @@ impl NapiResourceInstanceWrapper {
     // =========================================================================
 
     /// Create a wrapper for a given graph (must be registered).
+    ///
+    /// If `resource_id` is provided, a minimal resource metadata is created so
+    /// the tile-source fast path can look up tiles by resource.
     #[napi(constructor)]
-    pub fn new(graph_id: String) -> Result<Self> {
+    pub fn new(graph_id: String, _resource_id: Option<String>) -> Result<Self> {
         let graph = alizarin_core::get_graph(&graph_id).ok_or_else(|| {
             napi::Error::from_reason(format!(
                 "Graph '{}' not registered. Call registerGraph() first.",
@@ -516,6 +800,7 @@ impl NapiResourceInstanceWrapper {
         })?;
 
         let model_access = GraphModelAccess::from_graph(&graph);
+        // TODO: use resource_id with new_for_resource_id once tile-source plumbing is committed
         let mut core = ResourceInstanceWrapperCore::new(graph_id);
         core.set_cached_indices(&model_access);
 
@@ -530,19 +815,19 @@ impl NapiResourceInstanceWrapper {
     // Tile loading
     // =========================================================================
 
-    /// Load tiles from a JSON array.
+    /// Load tiles from a JSON string (single-pass deserialization).
     #[napi]
-    pub fn load_tiles(&mut self, tiles_js: serde_json::Value) -> Result<()> {
-        let tiles: Vec<StaticTile> = serde_json::from_value(tiles_js)
+    pub fn load_tiles(&mut self, tiles_json: String) -> Result<()> {
+        let tiles: Vec<StaticTile> = serde_json::from_str(&tiles_json)
             .map_err(|e| napi::Error::from_reason(format!("Invalid tiles JSON: {e}")))?;
         self.inner.load_tiles(tiles);
         Ok(())
     }
 
-    /// Load tiles directly from a StaticResource JSON.
+    /// Load tiles directly from a StaticResource JSON string (single-pass deserialization).
     #[napi]
-    pub fn load_tiles_from_resource(&mut self, resource_js: serde_json::Value) -> Result<()> {
-        let resource: StaticResource = serde_json::from_value(resource_js)
+    pub fn load_tiles_from_resource(&mut self, resource_json: String) -> Result<()> {
+        let resource: StaticResource = serde_json::from_str(&resource_json)
             .map_err(|e| napi::Error::from_reason(format!("Invalid resource JSON: {e}")))?;
 
         self.inner.resource_instance = Some(resource.resourceinstance.clone());
@@ -553,6 +838,27 @@ impl NapiResourceInstanceWrapper {
         Ok(())
     }
 
+    /// Load tiles directly from a NapiStaticResourceRegistry by resource ID.
+    /// This avoids the JS round-trip of serializing tiles to JS and back.
+    #[napi]
+    pub fn load_from_registry(
+        &mut self,
+        resource_id: String,
+        registry: &crate::NapiStaticResourceRegistry,
+    ) -> Result<bool> {
+        let resource = match registry.inner.get_full(&resource_id) {
+            Some(r) => r,
+            None => return Ok(false),
+        };
+
+        self.inner.resource_instance = Some(resource.resourceinstance.clone());
+
+        if let Some(tiles_vec) = &resource.tiles {
+            self.inner.load_tiles(tiles_vec.clone());
+        }
+        Ok(true)
+    }
+
     /// Append tiles incrementally (for lazy loading).
     #[napi]
     pub fn append_tiles(&mut self, tiles_js: serde_json::Value) -> Result<()> {
@@ -891,6 +1197,23 @@ impl NapiResourceInstanceWrapper {
     // Path resolution
     // =========================================================================
 
+    /// Resolve a dot-separated path to its target node metadata without needing tiles.
+    ///
+    /// Returns { nodegroupId, isSingle, targetNodeId } — enough for the JS layer to
+    /// lazy-load just that nodegroup's tiles before calling getValuesAtPath.
+    #[napi(js_name = "resolvePath")]
+    pub fn resolve_path(&self, path: String) -> Result<serde_json::Value> {
+        let info = self
+            .inner
+            .resolve_path(&path, &self.model_access)
+            .map_err(|e| napi::Error::from_reason(e.to_string()))?;
+        Ok(serde_json::json!({
+            "nodegroupId": info.nodegroup_id,
+            "isSingle": info.is_single,
+            "targetNodeId": info.target_node.nodeid,
+        }))
+    }
+
     /// Resolve a dot-separated path and return a PseudoList.
     #[napi]
     pub fn get_values_at_path(&self, path: String) -> Result<NapiPseudoList> {

package/src/lib.rs

@@ -1,4 +1,5 @@
 mod instance_wrapper_napi;
+use instance_wrapper_napi::NapiRdmCache;
 
 use std::collections::HashMap;
 use std::sync::OnceLock;
@@ -166,6 +167,21 @@ impl NapiStaticGraph {
     pub fn register(&self) {
         alizarin_core::register_graph_owned(self.inner.clone());
     }
+
+    /// Set a descriptor template for computing resource name/description/slug.
+    ///
+    /// Template placeholders use `<Node Name>` syntax, e.g. `"<Headword>"`.
+    /// Descriptor types: "name", "description", "slug".
+    #[napi(js_name = "setDescriptorTemplate")]
+    pub fn set_descriptor_template(
+        &mut self,
+        descriptor_type: String,
+        string_template: String,
+    ) -> Result<()> {
+        self.inner
+            .set_descriptor_template(&descriptor_type, &string_template)
+            .map_err(napi::Error::from_reason)
+    }
 }
 
 // ============================================================================
@@ -174,7 +190,7 @@ impl NapiStaticGraph {
 
 #[napi]
 pub struct NapiStaticResourceRegistry {
-    inner: StaticResourceRegistry,
+    pub(crate) inner: StaticResourceRegistry,
 }
 
 impl Default for NapiStaticResourceRegistry {
@@ -281,9 +297,12 @@ impl NapiStaticResourceRegistry {
         graph: &NapiStaticGraph,
         node_identifier: String,
         flatten_localized: Option<bool>,
+        rdm_cache: Option<&NapiRdmCache>,
     ) -> Result<HashMap<String, Vec<String>>> {
         let ctx = SerializationContext {
             extension_registry: Some(extension_registry()),
+            external_resolver: rdm_cache
+                .map(|r| r.inner() as &dyn alizarin_core::type_serialization::ExternalResolver),
             ..SerializationContext::empty()
         };
         self.inner
@@ -381,6 +400,63 @@ impl NapiStaticResourceRegistry {
             None => Ok(None),
         }
     }
+
+    /// Get diagnostic stats about registry contents (entry counts, tile counts, etc.)
+    #[napi]
+    pub fn memory_stats(&self) -> Result<serde_json::Value> {
+        let stats = self.inner.memory_stats();
+        serde_json::to_value(&stats)
+            .map_err(|e| napi::Error::from_reason(format!("Serialization failed: {}", e)))
+    }
+
+    /// Get detailed stats including estimated byte sizes (expensive — re-serializes all data)
+    #[napi]
+    pub fn memory_stats_detailed(&self) -> Result<serde_json::Value> {
+        let stats = self.inner.memory_stats_detailed();
+        serde_json::to_value(&stats)
+            .map_err(|e| napi::Error::from_reason(format!("Serialization failed: {}", e)))
+    }
+
+    /// Populate __cache on resources with summaries for referenced resources.
+    ///
+    /// Uses the graph to identify resource-instance nodes, then populates
+    /// cache entries for each referenced resource found in this registry.
+    ///
+    /// If `enrich_relationships` is true, also adds ontologyProperty to tile data.
+    /// If `recompute_descriptors` is true, recomputes resource name/description from
+    /// descriptor templates set on the graph.
+    ///
+    /// Returns `{ resources, unknownReferences, hasUnknown }`.
+    #[napi(js_name = "populateCachesFromJson")]
+    pub fn populate_caches_from_json(
+        &self,
+        resources_json: String,
+        graph: &NapiStaticGraph,
+        enrich_relationships: Option<bool>,
+        strict: Option<bool>,
+        recompute_descriptors: Option<bool>,
+    ) -> Result<serde_json::Value> {
+        let mut resources: Vec<StaticResource> = serde_json::from_str(&resources_json)
+            .map_err(|e| napi::Error::from_reason(format!("Failed to parse resources: {}", e)))?;
+
+        let result = self
+            .inner
+            .populate_caches(
+                &mut resources,
+                &graph.inner,
+                enrich_relationships.unwrap_or(true),
+                strict.unwrap_or(false),
+                recompute_descriptors.unwrap_or(false),
+            )
+            .map_err(napi::Error::from_reason)?;
+
+        let output = serde_json::json!({
+            "resources": resources,
+            "unknownReferences": result.unknown_references,
+            "hasUnknown": result.has_unknown_references(),
+        });
+        Ok(output)
+    }
 }
 
 // ============================================================================
@@ -443,15 +519,21 @@ pub fn build_business_data_from_csv(
     csv_data: String,
     graph_json: String,
     collections_json: String,
+    default_language: Option<String>,
+    strict_concepts: Option<bool>,
 ) -> Result<serde_json::Value> {
     let graph: StaticGraph = serde_json::from_str(&graph_json)
         .map_err(|e| napi::Error::from_reason(format!("Invalid graph JSON: {e}")))?;
     let collections: Vec<SkosCollection> = serde_json::from_str(&collections_json)
         .map_err(|e| napi::Error::from_reason(format!("Invalid collections JSON: {e}")))?;
 
-    let resources =
-        build_resources_from_business_csv(&csv_data, &graph, &collections, Default::default())
-            .map_err(csv_err)?;
+    let options = alizarin_core::csv_business_data_loader::BusinessDataCsvOptions {
+        default_language: default_language.unwrap_or_else(|| "en".to_string()),
+        strict_concepts: strict_concepts.unwrap_or(true),
+    };
+
+    let resources = build_resources_from_business_csv(&csv_data, &graph, &collections, options)
+        .map_err(csv_err)?;
 
     Ok(wrap_business_data(&resources))
 }
@@ -529,6 +611,142 @@ pub fn get_registered_extension_handlers() -> Vec<String> {
         .collect()
 }
 
+// ============================================================================
+// SKOS parsing
+// ============================================================================
+
+/// Parse SKOS RDF/XML and return all collections as a JSON array.
+#[napi(js_name = "parseSkosXml")]
+pub fn parse_skos_xml(xml_content: String, base_uri: String) -> Result<serde_json::Value> {
+    let collections = alizarin_core::skos::parse_skos_to_collections(&xml_content, &base_uri)
+        .map_err(napi::Error::from_reason)?;
+    serde_json::to_value(&collections).map_err(|e| napi::Error::from_reason(e.to_string()))
+}
+
+/// Parse SKOS RDF/XML and return a single collection (the first one found).
+#[napi(js_name = "parseSkosXmlToCollection")]
+pub fn parse_skos_xml_to_collection(
+    xml_content: String,
+    base_uri: String,
+) -> Result<serde_json::Value> {
+    let mut collections = alizarin_core::skos::parse_skos_to_collections(&xml_content, &base_uri)
+        .map_err(napi::Error::from_reason)?;
+    if collections.is_empty() {
+        return Err(napi::Error::from_reason(
+            "No SKOS ConceptScheme found in XML".to_string(),
+        ));
+    }
+    let collection = collections.remove(0);
+    serde_json::to_value(&collection).map_err(|e| napi::Error::from_reason(e.to_string()))
+}
+
+/// Serialize a single SkosCollection to SKOS RDF/XML.
+#[napi(js_name = "collectionToSkosXml")]
+pub fn collection_to_skos_xml_napi(
+    collection_json: serde_json::Value,
+    base_uri: String,
+) -> Result<String> {
+    let collection: SkosCollection = serde_json::from_value(collection_json).map_err(|e| {
+        napi::Error::from_reason(format!("Failed to deserialize collection: {}", e))
+    })?;
+    Ok(alizarin_core::skos::collection_to_skos_xml(
+        &collection,
+        &base_uri,
+    ))
+}
+
+/// Serialize multiple SkosCollections to SKOS RDF/XML.
+#[napi(js_name = "collectionsToSkosXml")]
+pub fn collections_to_skos_xml_napi(
+    collections_json: serde_json::Value,
+    base_uri: String,
+) -> Result<String> {
+    let collections: Vec<SkosCollection> =
+        serde_json::from_value(collections_json).map_err(|e| {
+            napi::Error::from_reason(format!("Failed to deserialize collections: {}", e))
+        })?;
+    Ok(alizarin_core::skos::collections_to_skos_xml(
+        &collections,
+        &base_uri,
+    ))
+}
+
+// ============================================================================
+// Label resolution utilities
+// ============================================================================
+
+/// Build a mapping from node alias to collection ID based on graph definition.
+///
+/// Equivalent to WASM's `buildAliasToCollectionMap`.
+#[napi(js_name = "buildAliasToCollectionMap")]
+pub fn build_alias_to_collection_map(
+    graph_json: String,
+    resolvable_datatypes: Option<Vec<String>>,
+    config_keys: Option<Vec<String>>,
+) -> Result<HashMap<String, String>> {
+    let graph: serde_json::Value = serde_json::from_str(&graph_json)
+        .map_err(|e| napi::Error::from_reason(format!("Invalid graph JSON: {e}")))?;
+
+    let config = alizarin_core::LabelResolutionConfig {
+        resolvable_datatypes: resolvable_datatypes.unwrap_or_else(|| {
+            alizarin_core::DEFAULT_RESOLVABLE_DATATYPES
+                .iter()
+                .map(|s| s.to_string())
+                .collect()
+        }),
+        config_keys: config_keys.unwrap_or_else(|| {
+            alizarin_core::DEFAULT_CONFIG_KEYS
+                .iter()
+                .map(|s| s.to_string())
+                .collect()
+        }),
+        strict: false,
+    };
+
+    Ok(alizarin_core::build_alias_to_collection_map(
+        &graph, &config,
+    ))
+}
+
+/// Scan a JSON tree to find which collections are needed for resolution.
+///
+/// Equivalent to WASM's `findNeededCollections`.
+#[napi(js_name = "findNeededCollections")]
+pub fn find_needed_collections(
+    tree_json: String,
+    alias_to_collection: HashMap<String, String>,
+) -> Result<Vec<String>> {
+    let tree: serde_json::Value = serde_json::from_str(&tree_json)
+        .map_err(|e| napi::Error::from_reason(format!("Invalid tree JSON: {e}")))?;
+
+    let needed = alizarin_core::find_needed_collections(&tree, &alias_to_collection);
+    Ok(needed.into_iter().collect())
+}
+
+/// Check if a string is a valid UUID.
+#[napi(js_name = "isValidUuid")]
+pub fn is_valid_uuid(s: String) -> bool {
+    alizarin_core::is_valid_uuid(&s)
+}
+
+/// Get the default resolvable datatypes (concept, concept-list).
+#[napi(js_name = "getDefaultResolvableDatatypes")]
+pub fn get_default_resolvable_datatypes() -> Vec<String> {
+    alizarin_core::DEFAULT_RESOLVABLE_DATATYPES
+        .iter()
+        .map(|s| s.to_string())
+        .collect()
+}
+
+/// Get the default config keys for collection IDs.
+#[napi(js_name = "getDefaultConfigKeys")]
+pub fn get_default_config_keys() -> Vec<String> {
+    alizarin_core::DEFAULT_CONFIG_KEYS
+        .iter()
+        .map(|s| s.to_string())
+        .collect()
+}
+
 // ============================================================================
 // Prebuild import (high-level convenience)
 // ============================================================================