@needle-tools/addressing 0.3.4-1790936280.dramatic-tiramisu.86ca165 → 0.4.0

package/src/anchor.ts

@@ -1,71 +1,71 @@
-/**
- * The name-anchor scheme: an element named `Door #needle` derives its deterministic id
- * from the text before the marker instead of (name, index, file hash) — so the id
- * survives content changes and asset re-uploads as long as the name stays.
- *
- * CONTRACT NOTE — the marker set is part of the id contract. Markers may be ADDED (new
- * names start anchoring), but never removed or re-prioritized, and every WRITER of ids
- * (this package's consumers: cloud upload, editors, CLI) must agree on the set before a
- * new marker ships — a writer that anchors on a marker another writer doesn't know mints
- * DIFFERENT ids for the same file. The anchored id only hashes the VALUE (not the
- * marker), so all markers are aliases into the same id space.
- */
-
-/** the original marker — kept as a named export for existing consumers */
-export const ANCHOR_MARKER = "#needle";
-
-/**
- * All recognized markers, matched longest-first so overlapping suffixes resolve
- * deterministically. Currently one entry; see the contract note before adding more.
- */
-export const ANCHOR_MARKERS: readonly string[] = [ANCHOR_MARKER];
-
-export type ParsedAnchor = {
-    /** the marker that matched (one of {@link ANCHOR_MARKERS}) */
-    marker: string;
-    /** the anchor value — the deterministic-id input */
-    value: string;
-};
-
-/**
- * Parse an element name against all recognized markers (case-insensitive suffix match).
- * Returns null when no marker matches or the anchor value is empty.
- */
-export function parseAnchor(rawName: string | null | undefined): ParsedAnchor | null {
-    if (rawName == null) return null;
-    const trimmed = rawName.trim();
-    const lower = trimmed.toLowerCase();
-    for (const marker of byLengthDescending(ANCHOR_MARKERS)) {
-        if (!lower.endsWith(marker)) continue;
-        const value = normalizeName(trimmed.substring(0, trimmed.length - marker.length));
-        return value.length > 0 ? { marker, value } : null;
-    }
-    return null;
-}
-
-/**
- * Names treat SPACES and UNDERSCORES as the same character (runs collapse to one space):
- * three's GLTFLoader sanitizes node names on load (whitespace becomes "_"), so
- * "Door Frame #needle" appears live as "Door_Frame_#needle" — without normalization a
- * stamped anchor and the live anchor would never match. Applied at PARSE time, so id
- * computation and resolution agree from one change point. Accepted trade: names differing
- * only by space-vs-underscore are one name.
- *
- * Exported because id derivation applies the SAME rule to unanchored names (see
- * {@link import("./id.js").idNameOf}) — one normalization, one change point.
- */
-export function normalizeName(value: string): string {
-    return value.replace(/[\s_]+/g, " ").trim();
-}
-
-/**
- * Extract the anchor value from an element name, or null when the name carries no anchor.
- * Convenience over {@link parseAnchor} for callers that only need the id input.
- */
-export function parseAnchorValue(rawName: string | null | undefined): string | null {
-    return parseAnchor(rawName)?.value ?? null;
-}
-
-function byLengthDescending(markers: readonly string[]): readonly string[] {
-    return markers.length > 1 ? [...markers].sort((a, b) => b.length - a.length) : markers;
-}
+/**
+ * The name-anchor scheme: an element named `Door #needle` derives its deterministic id
+ * from the text before the marker instead of (name, index, file hash) — so the id
+ * survives content changes and asset re-uploads as long as the name stays.
+ *
+ * CONTRACT NOTE — the marker set is part of the id contract. Markers may be ADDED (new
+ * names start anchoring), but never removed or re-prioritized, and every WRITER of ids
+ * (this package's consumers: cloud upload, editors, CLI) must agree on the set before a
+ * new marker ships — a writer that anchors on a marker another writer doesn't know mints
+ * DIFFERENT ids for the same file. The anchored id only hashes the VALUE (not the
+ * marker), so all markers are aliases into the same id space.
+ */
+
+/** the original marker — kept as a named export for existing consumers */
+export const ANCHOR_MARKER = "#needle";
+
+/**
+ * All recognized markers, matched longest-first so overlapping suffixes resolve
+ * deterministically. Currently one entry; see the contract note before adding more.
+ */
+export const ANCHOR_MARKERS: readonly string[] = [ANCHOR_MARKER];
+
+export type ParsedAnchor = {
+    /** the marker that matched (one of {@link ANCHOR_MARKERS}) */
+    marker: string;
+    /** the anchor value — the deterministic-id input */
+    value: string;
+};
+
+/**
+ * Parse an element name against all recognized markers (case-insensitive suffix match).
+ * Returns null when no marker matches or the anchor value is empty.
+ */
+export function parseAnchor(rawName: string | null | undefined): ParsedAnchor | null {
+    if (rawName == null) return null;
+    const trimmed = rawName.trim();
+    const lower = trimmed.toLowerCase();
+    for (const marker of byLengthDescending(ANCHOR_MARKERS)) {
+        if (!lower.endsWith(marker)) continue;
+        const value = normalizeName(trimmed.substring(0, trimmed.length - marker.length));
+        return value.length > 0 ? { marker, value } : null;
+    }
+    return null;
+}
+
+/**
+ * Names treat SPACES and UNDERSCORES as the same character (runs collapse to one space):
+ * three's GLTFLoader sanitizes node names on load (whitespace becomes "_"), so
+ * "Door Frame #needle" appears live as "Door_Frame_#needle" — without normalization a
+ * stamped anchor and the live anchor would never match. Applied at PARSE time, so id
+ * computation and resolution agree from one change point. Accepted trade: names differing
+ * only by space-vs-underscore are one name.
+ *
+ * Exported because id derivation applies the SAME rule to unanchored names (see
+ * {@link import("./id.js").idNameOf}) — one normalization, one change point.
+ */
+export function normalizeName(value: string): string {
+    return value.replace(/[\s_]+/g, " ").trim();
+}
+
+/**
+ * Extract the anchor value from an element name, or null when the name carries no anchor.
+ * Convenience over {@link parseAnchor} for callers that only need the id input.
+ */
+export function parseAnchorValue(rawName: string | null | undefined): string | null {
+    return parseAnchor(rawName)?.value ?? null;
+}
+
+function byLengthDescending(markers: readonly string[]): readonly string[] {
+    return markers.length > 1 ? [...markers].sort((a, b) => b.length - a.length) : markers;
+}

package/src/document/assets.ts

@@ -1,77 +1,77 @@
-import type { ProjectDocument, ProjectDocumentAsset, ProjectDocumentReference } from "./types.js";
-
-/** Asset keys and shared resource identities for one document assembly. */
-export class DocumentAssetAssembly {
-    private readonly assetBySrc = new Map<string, string>();
-    private readonly referenceById = new Map<string, ProjectDocumentReference>();
-    private readonly materialBySource = new Map<string, ProjectDocumentReference>();
-    private readonly baseMaterialBySource = new Map<string, ProjectDocumentReference>();
-
-    constructor(
-        private readonly assets: Record<string, ProjectDocumentAsset>,
-        private readonly references: ProjectDocumentReference[],
-        base?: ProjectDocument | null,
-    ) {
-        for (const [key, asset] of Object.entries(assets)) this.assetBySrc.set(asset.src, key);
-        for (const reference of references) {
-            this.referenceById.set(reference.id, reference);
-            const key = this.materialKey(reference, assets);
-            if (key) this.materialBySource.set(key, reference);
-        }
-        for (const reference of base?.references ?? []) {
-            const key = this.materialKey(reference, base?.assets ?? {});
-            if (key) this.baseMaterialBySource.set(key, reference);
-        }
-    }
-
-    addAsset(input: { src: string; name?: string; kind: string; identity?: { id: string; provider?: string } }): string {
-        const existing = this.assetBySrc.get(input.src);
-        if (existing !== undefined) return existing;
-        const filename = input.src.split("?")[0].split("/").pop() || "material";
-        const dot = filename.lastIndexOf(".");
-        const stem = input.name || (dot > 0 ? filename.substring(0, dot) : filename);
-        let key = stem;
-        let n = 2;
-        while (key in this.assets) key = `${stem}-${n++}`;
-        this.assets[key] = { src: input.src, kind: input.kind, ...(input.identity ? { asset: { ...input.identity } } : {}) };
-        this.assetBySrc.set(input.src, key);
-        return key;
-    }
-
-    materialEntity(asset: string, material: { id: string; name?: string }, entityId: string): string {
-        if (!this.assets[asset]) throw new Error(`Unknown document asset: ${asset}`);
-        const key = JSON.stringify([this.assets[asset].src, material.id]);
-        const existing = this.materialBySource.get(key);
-        if (existing) return existing.id;
-        const base = this.baseMaterialBySource.get(key);
-        const reference: ProjectDocumentReference = base ? { ...base, asset } : {
-            id: entityId, asset, address: { type: "material", id: material.id, ...(material.name ? { name: material.name } : {}) },
-        };
-        this.addReference(reference);
-        this.materialBySource.set(key, reference);
-        return reference.id;
-    }
-
-    environmentEntity(asset: string, entityId: string): string {
-        if (!this.assets[asset]) throw new Error(`Unknown document asset: ${asset}`);
-        this.addReference({ id: entityId, asset, address: { type: "hdr" } });
-        return entityId;
-    }
-
-    private addReference(reference: ProjectDocumentReference): void {
-        const existing = this.referenceById.get(reference.id);
-        if (existing) {
-            if (existing.asset !== reference.asset || existing.address?.type !== reference.address?.type || existing.address?.id !== reference.address?.id) {
-                throw new Error(`Document reference id '${reference.id}' already identifies another resource`);
-            }
-            return;
-        }
-        this.references.push(reference);
-        this.referenceById.set(reference.id, reference);
-    }
-
-    private materialKey(reference: ProjectDocumentReference, assets: Record<string, ProjectDocumentAsset>): string | null {
-        return reference.address?.type === "material" && reference.address.id && assets[reference.asset]
-            ? JSON.stringify([assets[reference.asset].src, reference.address.id]) : null;
-    }
-}
+import type { ProjectDocument, ProjectDocumentAsset, ProjectDocumentReference } from "./types.js";
+
+/** Asset keys and shared resource identities for one document assembly. */
+export class DocumentAssetAssembly {
+    private readonly assetBySrc = new Map<string, string>();
+    private readonly referenceById = new Map<string, ProjectDocumentReference>();
+    private readonly materialBySource = new Map<string, ProjectDocumentReference>();
+    private readonly baseMaterialBySource = new Map<string, ProjectDocumentReference>();
+
+    constructor(
+        private readonly assets: Record<string, ProjectDocumentAsset>,
+        private readonly references: ProjectDocumentReference[],
+        base?: ProjectDocument | null,
+    ) {
+        for (const [key, asset] of Object.entries(assets)) this.assetBySrc.set(asset.src, key);
+        for (const reference of references) {
+            this.referenceById.set(reference.id, reference);
+            const key = this.materialKey(reference, assets);
+            if (key) this.materialBySource.set(key, reference);
+        }
+        for (const reference of base?.references ?? []) {
+            const key = this.materialKey(reference, base?.assets ?? {});
+            if (key) this.baseMaterialBySource.set(key, reference);
+        }
+    }
+
+    addAsset(input: { src: string; name?: string; kind: string; identity?: { id: string; provider?: string } }): string {
+        const existing = this.assetBySrc.get(input.src);
+        if (existing !== undefined) return existing;
+        const filename = input.src.split("?")[0].split("/").pop() || "material";
+        const dot = filename.lastIndexOf(".");
+        const stem = input.name || (dot > 0 ? filename.substring(0, dot) : filename);
+        let key = stem;
+        let n = 2;
+        while (key in this.assets) key = `${stem}-${n++}`;
+        this.assets[key] = { src: input.src, kind: input.kind, ...(input.identity ? { asset: { ...input.identity } } : {}) };
+        this.assetBySrc.set(input.src, key);
+        return key;
+    }
+
+    materialEntity(asset: string, material: { id: string; name?: string }, entityId: string): string {
+        if (!this.assets[asset]) throw new Error(`Unknown document asset: ${asset}`);
+        const key = JSON.stringify([this.assets[asset].src, material.id]);
+        const existing = this.materialBySource.get(key);
+        if (existing) return existing.id;
+        const base = this.baseMaterialBySource.get(key);
+        const reference: ProjectDocumentReference = base ? { ...base, asset } : {
+            id: entityId, asset, address: { type: "material", id: material.id, ...(material.name ? { name: material.name } : {}) },
+        };
+        this.addReference(reference);
+        this.materialBySource.set(key, reference);
+        return reference.id;
+    }
+
+    environmentEntity(asset: string, entityId: string): string {
+        if (!this.assets[asset]) throw new Error(`Unknown document asset: ${asset}`);
+        this.addReference({ id: entityId, asset, address: { type: "hdr" } });
+        return entityId;
+    }
+
+    private addReference(reference: ProjectDocumentReference): void {
+        const existing = this.referenceById.get(reference.id);
+        if (existing) {
+            if (existing.asset !== reference.asset || existing.address?.type !== reference.address?.type || existing.address?.id !== reference.address?.id) {
+                throw new Error(`Document reference id '${reference.id}' already identifies another resource`);
+            }
+            return;
+        }
+        this.references.push(reference);
+        this.referenceById.set(reference.id, reference);
+    }
+
+    private materialKey(reference: ProjectDocumentReference, assets: Record<string, ProjectDocumentAsset>): string | null {
+        return reference.address?.type === "material" && reference.address.id && assets[reference.asset]
+            ? JSON.stringify([assets[reference.asset].src, reference.address.id]) : null;
+    }
+}

package/src/document/collectionSelector.ts

@@ -1,37 +1,37 @@
-export interface DocumentCollectionSelectorOptions {
-    matchesComponentType?(component: object, name: string): boolean;
-    matchesComponentGuid?(component: object, guid: string): boolean;
-    deriveComponentGuid?(referenceId: string, fileGuid: string): string;
-    referenceId?: string;
-    report?(message: string): void;
-}
-
-/** Resolve an index or field qualifier; ambiguous identities never select an arbitrary member. */
-export function resolveDocumentCollectionElement(
-    collection: readonly unknown[], selector: string, options: DocumentCollectionSelectorOptions = {},
-): unknown {
-    if (/^\d+$/.test(selector)) return collection[Number(selector)];
-    const qualifier = /^([A-Za-z_][A-Za-z0-9_-]*):([\s\S]*)$/.exec(selector);
-    if (!qualifier) {
-        options.report?.(`"${selector}" is neither an index nor a <field>:<value> qualifier`);
-        return undefined;
-    }
-    const [, field, value] = qualifier;
-    const elements = collection.filter((element): element is Record<string, unknown> =>
-        element !== null && typeof element === "object");
-    let matches = elements.filter(element => {
-        if (field === "type") return options.matchesComponentType?.(element, value) ?? element.constructor?.name === value;
-        if (field === "guid") return options.matchesComponentGuid?.(element, value)
-            ?? (element.guid === value || element.needle_editor_guid === value);
-        return element[field] === value;
-    });
-    if (!matches.length && field === "guid" && options.referenceId && options.deriveComponentGuid) {
-        const derived = options.deriveComponentGuid(options.referenceId, value);
-        matches = elements.filter(element => element.guid === derived);
-    }
-    if (matches.length > 1) {
-        options.report?.(`"${selector}" matched ${matches.length} elements ? the document must name one unambiguously`);
-        return undefined;
-    }
-    return matches[0];
-}
+export interface DocumentCollectionSelectorOptions {
+    matchesComponentType?(component: object, name: string): boolean;
+    matchesComponentGuid?(component: object, guid: string): boolean;
+    deriveComponentGuid?(referenceId: string, fileGuid: string): string;
+    referenceId?: string;
+    report?(message: string): void;
+}
+
+/** Resolve an index or field qualifier; ambiguous identities never select an arbitrary member. */
+export function resolveDocumentCollectionElement(
+    collection: readonly unknown[], selector: string, options: DocumentCollectionSelectorOptions = {},
+): unknown {
+    if (/^\d+$/.test(selector)) return collection[Number(selector)];
+    const qualifier = /^([A-Za-z_][A-Za-z0-9_-]*):([\s\S]*)$/.exec(selector);
+    if (!qualifier) {
+        options.report?.(`"${selector}" is neither an index nor a <field>:<value> qualifier`);
+        return undefined;
+    }
+    const [, field, value] = qualifier;
+    const elements = collection.filter((element): element is Record<string, unknown> =>
+        element !== null && typeof element === "object");
+    let matches = elements.filter(element => {
+        if (field === "type") return options.matchesComponentType?.(element, value) ?? element.constructor?.name === value;
+        if (field === "guid") return options.matchesComponentGuid?.(element, value)
+            ?? (element.guid === value || element.needle_editor_guid === value);
+        return element[field] === value;
+    });
+    if (!matches.length && field === "guid" && options.referenceId && options.deriveComponentGuid) {
+        const derived = options.deriveComponentGuid(options.referenceId, value);
+        matches = elements.filter(element => element.guid === derived);
+    }
+    if (matches.length > 1) {
+        options.report?.(`"${selector}" matched ${matches.length} elements ? the document must name one unambiguously`);
+        return undefined;
+    }
+    return matches[0];
+}