@needle-tools/addressing 0.1.0 → 0.1.1

package/Readme.md

@@ -1,89 +1,66 @@
-# @needle-tools/addressing
-
-Persistent addressing for Needle assets: deterministic `needle-id` computation, the
-`#needle` anchor scheme, and address resolution over glTF JSON and live scene graphs.
-
-Zero runtime dependencies, no three.js or engine import (duck-typed scene graphs), usable
-in browsers, node, and workers. This package is the **single implementation of the
-addressing contract** shared by needle-cloud (upload-time id injection), the Needle
-editors (load-time computation, address records for edits/marks/overlays), and Needle
-Engine (project-document resolution at load).
-
-## The contract
-
-### Deterministic ids (`needle-id`)
-
-Every glTF root-collection element (nodes, scenes, animations, cameras, materials,
-meshes, skins, textures, images, samplers) gets a UUID in `extras["needle-id"]`:
-
-- **Anchored** — name ends with `#needle` (case-insensitive):
-  `uuidv5("<type>-<anchor>", URL_NAMESPACE)`. Independent of index and file content →
-  **survives asset updates** as long as the name stays.
-- **Unanchored**: `uuidv5("<type>-<name>-<index>-<fileHash>", URL_NAMESPACE)` where
-  `fileHash = md5hex(JSON.stringify(json))` of the file **before any injection**.
-  Stable per asset *version* only — re-uploading changed content changes these ids
-  (by design: same-named elements in different files must not collide).
-
-Compatibility is pinned by golden tests against the original implementation
-(needle-cloud `gltf.edit.ts` `ensureUUID`, real `js-md5` + `uuid` packages). This
-includes a frozen quirk: the anchor value's cut index is computed from the trimmed name
-but applied to the raw name, so leading whitespace shifts the anchor
-(`"  Trim#NEEDLE"` → anchor `"Tr"`). Do not "fix" this — it would change every anchored
-id minted for such names.
-
-### Who writes ids when
-
-- **needle-cloud**: injects on upload (frontend today; CLI/optimizer parity planned).
-- **Editors**: **eager compute, lazy persist.** Compute ids at LOAD time against the
-  pristine JSON (the inputs — original name, index, file hash — only exist pristinely
-  then; computing after edits breaks determinism). Persist into the file only on save.
-  A locally saved file is stamped identically to a cloud upload of the same bytes.
-- **Scratch content** (created in an editor, no source file): `randomUuid()` at creation.
-
-### Address records
-
-An address is "fat": every fallback is captured at creation time, while the target is
-known — `{ id, anchor?, type?, name?, namePath? }`. Resolution order is strict:
-
-1. `id` — exact match (extras in glTF, `userData` in live graphs)
-2. `anchor` — survives asset updates
-3. `namePath` — best-effort structural match
-4. **reconciliation** — never automatic: `reconcileInGraph` returns ranked candidates
-   with confidence + reasons; the caller decides thresholds and whether to re-anchor.
-
-## API
-
-```ts
-import {
-    ensureIds, computeElementId, computeFileHash,         // write side
-    createGltfElementAddress, createObjectAddress,        // address records
-    resolveInGltf, resolveInGraph, reconcileInGraph,      // resolve side
-    parseAnchorValue, randomUuid, NEEDLE_ID_KEY,
-} from "@needle-tools/addressing";
-
-// stamp a parsed glTF (idempotent, never overwrites existing ids)
-const { fileHash, assigned } = ensureIds(gltfJson);
-
-// capture an address while the target is known
-const address = createObjectAddress(sceneRoot, targetObject);
-
-// later / elsewhere: resolve — or reconcile when the asset changed
-const hit = resolveInGraph(address, sceneRoot);
-const candidates = hit ? [] : reconcileInGraph(address, sceneRoot);
-```
-
-Out of scope by design: GLB container parsing (callers own their binary handling — this
-package takes parsed JSON), file I/O, session-scoped editor refs, and any composition/
-override semantics (those live in the project format, one layer above).
-
-## Development
-
-```
-npm install
-npm test        # vitest — includes byte-parity golden tests
-npm run build   # tsc → dist/
-```
-
-Regenerating `test/fixtures/golden.json` requires the reference libraries
-(`js-md5`, `uuid`) and a verbatim copy of needle-cloud's `ensureUUID` — see the
-fixture header comment in `test/id.test.ts`.
+# @needle-tools/addressing
+
+Persistent addressing for glTF assets and three.js scene graphs: deterministic
+`needle-id` computation, the `#needle` name-anchor scheme, and address resolution.
+
+Zero runtime dependencies, no three.js import (scene graphs are accessed structurally),
+usable in browsers, node, and workers.
+
+## Ids
+
+Every glTF root-collection element (nodes, scenes, animations, cameras, materials,
+meshes, skins, textures, images, samplers) can carry a UUID in `extras["needle-id"]`:
+
+- **Anchored** — the element name ends with `#needle` (case-insensitive): the id derives
+  only from the text before the marker → it **survives content changes and re-exports**
+  as long as the name stays.
+- **Unanchored**: the id derives from the element's type, name, index and a fingerprint
+  of the whole file → stable per asset *version* (same-named elements in different files
+  never collide).
+
+`ensureIds(gltfJson)` stamps a parsed glTF idempotently — existing ids are never
+overwritten, and stamping the same bytes always mints the same ids, no matter which tool
+does it.
+
+## Addresses
+
+An address captures every fallback at creation time, while the target is known —
+`{ id, anchor?, type?, name?, namePath? }`. Resolution order is strict:
+
+1. `id` — exact match (`extras` in glTF JSON, `userData` in live scene graphs)
+2. `anchor` — survives asset updates
+3. `namePath` — best-effort structural match
+4. **reconciliation** — never automatic: `reconcileInGraph` returns ranked candidates
+   with confidence + reasons; the caller decides thresholds and whether to re-anchor.
+
+## API
+
+```ts
+import {
+    ensureIds, computeElementId, computeFileHash,         // write side
+    createGltfElementAddress, createObjectAddress,        // address records
+    resolveInGltf, resolveInGraph, reconcileInGraph,      // resolve side
+    parseAnchorValue, randomUuid, NEEDLE_ID_KEY,
+} from "@needle-tools/addressing";
+
+// stamp a parsed glTF (idempotent, never overwrites existing ids)
+const { fileHash, assigned } = ensureIds(gltfJson);
+
+// capture an address while the target is known
+const address = createObjectAddress(sceneRoot, targetObject);
+
+// later / elsewhere: resolve — or reconcile when the asset changed
+const hit = resolveInGraph(address, sceneRoot);
+const candidates = hit ? [] : reconcileInGraph(address, sceneRoot);
+```
+
+Out of scope by design: GLB container parsing (this package takes parsed JSON), file
+I/O, and any composition/override semantics.
+
+## Development
+
+```
+npm install
+npm test        # vitest — includes golden-fixture id tests
+npm run build   # tsc → dist/
+```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@needle-tools/addressing",
-    "version": "0.1.0",
+    "version": "0.1.1",
     "description": "Persistent addressing for Needle assets: deterministic needle-id computation, #needle anchors, and address resolution over glTF JSON and live scene graphs.",
     "type": "module",
     "main": "./src/index.ts",

package/src/anchor.ts

@@ -37,9 +37,7 @@ export function parseAnchor(rawName: string | null | undefined): ParsedAnchor |
     const lower = trimmed.toLowerCase();
     for (const marker of byLengthDescending(ANCHOR_MARKERS)) {
         if (!lower.endsWith(marker)) continue;
-        const value = marker === ANCHOR_MARKER
-            ? legacyNeedleAnchorValue(rawName, trimmed)
-            : trimmed.substring(0, trimmed.length - marker.length).trim();
+        const value = trimmed.substring(0, trimmed.length - marker.length).trim();
         return value.length > 0 ? { marker, value } : null;
     }
     return null;
@@ -53,19 +51,6 @@ export function parseAnchorValue(rawName: string | null | undefined): string | n
     return parseAnchor(rawName)?.value ?? null;
 }
 
-/**
- * `#needle` value extraction, bug-compatible with needle-cloud's `ensureUUID`
- * (`gltf.edit.ts`), which computes the cut index from the TRIMMED name but applies it to
- * the RAW name: a name with leading whitespace yields a shifted (shorter) anchor value
- * (`"  Trim#NEEDLE"` → `"Tr"`). Anchored ids are the ids that must survive asset
- * updates, so this quirk is frozen into the contract for THIS marker — fixing it would
- * change every anchored id ever minted for such names. Future markers use the clean
- * trimmed parsing in {@link parseAnchor} instead.
- */
-function legacyNeedleAnchorValue(rawName: string, trimmed: string): string {
-    return rawName.substring(0, trimmed.length - ANCHOR_MARKER.length).trim();
-}
-
 function byLengthDescending(markers: readonly string[]): readonly string[] {
     return markers.length > 1 ? [...markers].sort((a, b) => b.length - a.length) : markers;
 }