@dxos/react-ui-attention 0.8.4-main.dedc0f3 → 0.8.4-main.e00bdcdb52

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@dxos/react-ui-attention",
-  "version": "0.8.4-main.dedc0f3",
+  "version": "0.8.4-main.e00bdcdb52",
   "description": "Signifier components and providers for attention system.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
   "license": "MIT",
   "author": "DXOS.org",
-  "sideEffects": true,
+  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
@@ -15,6 +19,12 @@
       "browser": "./dist/lib/browser/index.mjs",
       "node": "./dist/lib/node-esm/index.mjs"
     },
+    "./types": {
+      "source": "./src/types.ts",
+      "types": "./dist/types/src/types.d.ts",
+      "browser": "./dist/lib/browser/types.mjs",
+      "node": "./dist/lib/node-esm/types.mjs"
+    },
     "./testing": {
       "source": "./src/testing/index.ts",
       "types": "./dist/types/src/testing/index.d.ts",
@@ -23,20 +33,12 @@
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "testing": [
-        "dist/types/src/testing/index.d.ts"
-      ]
-    }
-  },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "@preact-signals/safe-react": "^0.9.0",
-    "@preact/signals-core": "^1.9.0",
+    "@effect-atom/atom-react": "^0.5.0",
     "@radix-ui/primitive": "1.1.1",
     "@radix-ui/react-compose-refs": "1.1.1",
     "@radix-ui/react-context": "1.1.1",
@@ -44,30 +46,30 @@
     "@radix-ui/react-primitive": "2.0.2",
     "@radix-ui/react-slot": "1.1.2",
     "@radix-ui/react-use-controllable-state": "1.1.0",
-    "effect": "3.17.7",
-    "@dxos/echo-schema": "0.8.4-main.dedc0f3",
-    "@dxos/invariant": "0.8.4-main.dedc0f3",
-    "@dxos/live-object": "0.8.4-main.dedc0f3",
-    "@dxos/log": "0.8.4-main.dedc0f3",
-    "@dxos/util": "0.8.4-main.dedc0f3"
+    "effect": "3.20.0",
+    "@dxos/invariant": "0.8.4-main.e00bdcdb52",
+    "@dxos/echo": "0.8.4-main.e00bdcdb52",
+    "@dxos/react-hooks": "0.8.4-main.e00bdcdb52",
+    "@dxos/util": "0.8.4-main.e00bdcdb52",
+    "@dxos/log": "0.8.4-main.e00bdcdb52"
   },
   "devDependencies": {
-    "@types/react": "~18.2.0",
-    "@types/react-dom": "~18.2.0",
-    "react": "~18.2.0",
-    "react-dom": "~18.2.0",
-    "vite": "7.1.1",
-    "@dxos/react-ui": "0.8.4-main.dedc0f3",
-    "@dxos/random": "0.8.4-main.dedc0f3",
-    "@dxos/react-ui-theme": "0.8.4-main.dedc0f3",
-    "@dxos/storybook-utils": "0.8.4-main.dedc0f3"
+    "@types/react": "~19.2.7",
+    "@types/react-dom": "~19.2.3",
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3",
+    "vite": "^8.0.10",
+    "@dxos/random": "0.8.4-main.e00bdcdb52",
+    "@dxos/react-ui": "0.8.4-main.e00bdcdb52",
+    "@dxos/ui-theme": "0.8.4-main.e00bdcdb52",
+    "@dxos/storybook-utils": "0.8.4-main.e00bdcdb52"
   },
   "peerDependencies": {
-    "effect": "^3.13.3",
-    "react": "~18.2.0",
-    "react-dom": "~18.2.0",
-    "@dxos/react-ui": "0.8.4-main.dedc0f3",
-    "@dxos/react-ui-theme": "0.8.4-main.dedc0f3"
+    "effect": "3.20.0",
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3",
+    "@dxos/react-ui": "0.8.4-main.e00bdcdb52",
+    "@dxos/ui-theme": "0.8.4-main.e00bdcdb52"
   },
   "publishConfig": {
     "access": "public"

package/src/attention.test.ts

@@ -2,46 +2,207 @@
 // Copyright 2024 DXOS.org
 //
 
-import { describe, expect, test } from 'vitest';
+import { Registry } from '@effect-atom/atom-react';
+import { describe, test } from 'vitest';
 
-import { AttentionManager } from './attention';
+import {
+  AttentionManager,
+  expandAttendableId,
+  getLinkedVariant,
+  getParentId,
+  getSegmentId,
+  isLinkedSegment,
+  linkedSegment,
+} from './attention';
 
 describe('AttentionManager', () => {
-  test('takes an initial attendable', () => {
-    const attention = new AttentionManager(['a', 'b', 'c']);
-    expect(attention.current).to.deep.equal(['a', 'b', 'c']);
-    expect(attention.keys()).to.deep.equal([['a'], ['b', 'c'], ['c'], ['a', 'b', 'c']]);
-    expect(attention.get(['a'])).to.deep.equal({ hasAttention: false, isAncestor: false, isRelated: true });
-    expect(attention.get(['b', 'c'])).to.deep.equal({ hasAttention: false, isAncestor: true, isRelated: false });
-    expect(attention.get(['c'])).to.deep.equal({ hasAttention: false, isAncestor: true, isRelated: false });
-    expect(attention.get(['a', 'b', 'c'])).to.deep.equal({ hasAttention: true, isAncestor: false, isRelated: false });
-    expect(attention.get(['b'])).to.deep.equal({ hasAttention: false, isAncestor: false, isRelated: false });
+  test('takes an initial attended id', ({ expect }) => {
+    const registry = Registry.make();
+    const attention = new AttentionManager(registry, ['root/a/b']);
+
+    expect(attention.getCurrent()).to.deep.equal(['root/a/b']);
+    expect(attention.get('root')).to.deep.equal({ hasAttention: false, isAncestor: true, isRelated: false });
+    expect(attention.get('root/a')).to.deep.equal({ hasAttention: false, isAncestor: true, isRelated: false });
+    expect(attention.get('root/a/b')).to.deep.equal({ hasAttention: true, isAncestor: false, isRelated: false });
+    expect(attention.get('unrelated')).to.deep.equal({ hasAttention: false, isAncestor: false, isRelated: false });
   });
 
-  test('current returns last updated key', () => {
-    const attention = new AttentionManager();
-    expect(attention.current).to.deep.equal([]);
+  test('current returns last updated ids', ({ expect }) => {
+    const registry = Registry.make();
+    const attention = new AttentionManager(registry);
+    expect(attention.getCurrent()).to.deep.equal([]);
 
-    attention.update(['a', 'b', 'c']);
-    expect(attention.current).to.deep.equal(['a', 'b', 'c']);
+    attention.update(['root/a/b/c']);
+    expect(attention.getCurrent()).to.deep.equal(['root/a/b/c']);
   });
 
-  test('keys returns all stored attendables', () => {
-    const attention = new AttentionManager();
+  test('keys returns all tracked qualified ids', ({ expect }) => {
+    const registry = Registry.make();
+    const attention = new AttentionManager(registry);
     expect(attention.keys()).to.deep.equal([]);
 
-    attention.update(['a']);
-    expect(attention.keys()).to.deep.equal([['a']]);
+    attention.update(['root/a']);
+    expect(attention.keys()).to.include('root');
+    expect(attention.keys()).to.include('root/a');
+  });
+
+  test('get returns attention state for a given qualified id', ({ expect }) => {
+    const registry = Registry.make();
+    const attention = new AttentionManager(registry);
+    expect(attention.get('root/a')).to.deep.equal({ hasAttention: false, isAncestor: false, isRelated: false });
 
-    attention.update(['a', 'b']);
-    expect(attention.keys()).to.deep.equal([['a'], ['b'], ['a', 'b']]);
+    attention.update(['root/a']);
+    expect(attention.get('root/a')).to.deep.equal({ hasAttention: true, isAncestor: false, isRelated: false });
+    expect(attention.get('root')).to.deep.equal({ hasAttention: false, isAncestor: true, isRelated: false });
   });
 
-  test('get returns attention object for a given key', () => {
-    const attention = new AttentionManager();
-    expect(attention.get(['a'])).to.deep.equal({ hasAttention: false, isAncestor: false, isRelated: false });
+  test('clears previous attention on update', ({ expect }) => {
+    const registry = Registry.make();
+    const attention = new AttentionManager(registry);
+
+    attention.update(['root/a/b']);
+    expect(attention.get('root/a/b')).to.deep.equal({ hasAttention: true, isAncestor: false, isRelated: false });
+    expect(attention.get('root/a')).to.deep.equal({ hasAttention: false, isAncestor: true, isRelated: false });
+
+    attention.update(['root/x/y']);
+    expect(attention.get('root/a/b')).to.deep.equal({ hasAttention: false, isAncestor: false, isRelated: false });
+    expect(attention.get('root/a')).to.deep.equal({ hasAttention: false, isAncestor: false, isRelated: false });
+    expect(attention.get('root/x/y')).to.deep.equal({ hasAttention: true, isAncestor: false, isRelated: false });
+    expect(attention.get('root/x')).to.deep.equal({ hasAttention: false, isAncestor: true, isRelated: false });
+    expect(attention.get('root')).to.deep.equal({ hasAttention: false, isAncestor: true, isRelated: false });
+  });
+
+  test('linked segment marks parent with isRelated and isAncestor', ({ expect }) => {
+    const registry = Registry.make();
+    const attention = new AttentionManager(registry);
+
+    attention.update(['root/space/obj/~settings']);
+    expect(attention.get('root/space/obj/~settings')).to.deep.equal({
+      hasAttention: true,
+      isAncestor: false,
+      isRelated: false,
+    });
+    expect(attention.get('root/space/obj')).to.deep.equal({
+      hasAttention: false,
+      isAncestor: true,
+      isRelated: true,
+    });
+    expect(attention.get('root/space')).to.deep.equal({
+      hasAttention: false,
+      isAncestor: true,
+      isRelated: false,
+    });
+    expect(attention.get('root')).to.deep.equal({
+      hasAttention: false,
+      isAncestor: true,
+      isRelated: false,
+    });
+  });
+
+  test('switching from linked segment to non-linked clears parent isRelated', ({ expect }) => {
+    const registry = Registry.make();
+    const attention = new AttentionManager(registry);
+
+    attention.update(['root/space/obj/~settings']);
+    expect(attention.get('root/space/obj')).to.deep.equal({
+      hasAttention: false,
+      isAncestor: true,
+      isRelated: true,
+    });
+
+    attention.update(['root/space/obj']);
+    expect(attention.get('root/space/obj')).to.deep.equal({
+      hasAttention: true,
+      isAncestor: false,
+      isRelated: false,
+    });
+    expect(attention.get('root/space/obj/~settings')).to.deep.equal({
+      hasAttention: false,
+      isAncestor: false,
+      isRelated: false,
+    });
+  });
+
+  test('keys sharing the same segment id are marked isRelated', ({ expect }) => {
+    const registry = Registry.make();
+    const attention = new AttentionManager(registry);
+
+    // Pre-register the alternate path so the manager knows about it.
+    attention.get('root/z/y/c');
+
+    attention.update(['root/a/b/c']);
+    expect(attention.get('root/a/b/c')).to.deep.equal({ hasAttention: true, isAncestor: false, isRelated: false });
+    expect(attention.get('root/z/y/c')).to.deep.equal({ hasAttention: false, isAncestor: false, isRelated: true });
+  });
+
+  test('related keys are cleared when attention moves to a different segment id', ({ expect }) => {
+    const registry = Registry.make();
+    const attention = new AttentionManager(registry);
+
+    attention.get('root/z/y/c');
+    attention.update(['root/a/b/c']);
+    expect(attention.get('root/z/y/c')).to.deep.equal({ hasAttention: false, isAncestor: false, isRelated: true });
+
+    attention.update(['root/x/y/d']);
+    expect(attention.get('root/z/y/c')).to.deep.equal({ hasAttention: false, isAncestor: false, isRelated: false });
+    expect(attention.get('root/a/b/c')).to.deep.equal({ hasAttention: false, isAncestor: false, isRelated: false });
+  });
+});
+
+describe('expandAttendableId', () => {
+  test('produces progressive prefixes', ({ expect }) => {
+    expect(expandAttendableId('root/space/types/doc')).to.deep.equal([
+      'root',
+      'root/space',
+      'root/space/types',
+      'root/space/types/doc',
+    ]);
+  });
+
+  test('single segment returns itself', ({ expect }) => {
+    expect(expandAttendableId('root')).to.deep.equal(['root']);
+  });
+});
+
+describe('isLinkedSegment', () => {
+  test('detects linked prefix on last segment', ({ expect }) => {
+    expect(isLinkedSegment('root/space/obj/~settings')).toBe(true);
+    expect(isLinkedSegment('root/space/obj')).toBe(false);
+    expect(isLinkedSegment('~standalone')).toBe(true);
+  });
+});
+
+describe('linkedSegment', () => {
+  test('builds a linked segment', ({ expect }) => {
+    expect(linkedSegment('settings')).toBe('~settings');
+    expect(linkedSegment('comments')).toBe('~comments');
+  });
+});
+
+describe('getLinkedVariant', () => {
+  test('extracts variant from linked last segment', ({ expect }) => {
+    expect(getLinkedVariant('root/space/obj/~settings')).toBe('settings');
+    expect(getLinkedVariant('root/a/~comments')).toBe('comments');
+  });
+
+  test('returns segment as-is when not linked', ({ expect }) => {
+    expect(getLinkedVariant('root/space/obj')).toBe('obj');
+    expect(getLinkedVariant('root')).toBe('root');
+  });
+});
+
+describe('getParentId', () => {
+  test('returns parent qualified id', ({ expect }) => {
+    expect(getParentId('root/space/obj/~settings')).toBe('root/space/obj');
+    expect(getParentId('root/space')).toBe('root');
+    expect(getParentId('root')).toBeUndefined();
+  });
+});
 
-    attention.update(['a']);
-    expect(attention.get(['a'])).to.deep.equal({ hasAttention: true, isAncestor: false, isRelated: false });
+describe('getSegmentId', () => {
+  test('returns the last path segment', ({ expect }) => {
+    expect(getSegmentId('root/space/obj')).toBe('obj');
+    expect(getSegmentId('root')).toBe('root');
+    expect(getSegmentId('root/a/~settings')).toBe('~settings');
   });
 });

package/src/attention.ts

@@ -2,119 +2,162 @@
 // Copyright 2024 DXOS.org
 //
 
-import { untracked } from '@preact/signals-core';
-import { Schema } from 'effect';
+import { Atom, type Registry } from '@effect-atom/atom-react';
 
-import { type Live, live } from '@dxos/live-object';
-import { ComplexMap } from '@dxos/util';
-
-// NOTE: Chosen from RFC 1738’s `safe` characters: http://www.faqs.org/rfcs/rfc1738.html
-export const ATTENDABLE_PATH_SEPARATOR = '~';
-
-export const AttentionSchema = Schema.mutable(
-  Schema.Struct({
-    hasAttention: Schema.Boolean,
-    isAncestor: Schema.Boolean,
-    isRelated: Schema.Boolean,
-  }),
-);
-
-export type Attention = Schema.Schema.Type<typeof AttentionSchema>;
-
-// TODO(wittjosiah): Use mosaic path utility?
-const stringKey = (key: string[]) => key.join(',');
+import { type Attention } from './types';
 
 /**
  * Manages attention state for an application.
+ * Attention keys are slash-qualified graph IDs; ancestry is derived from progressive prefixes.
  */
-// TODO(wittjosiah): Write unit tests.
 export class AttentionManager {
-  // Each attention path is associated with an attention object.
-  // The lookup is not a reactive object to ensure that attention for each path is subscribable independently.
-  private readonly _map = new ComplexMap<string[], Live<Attention>>(stringKey);
-  private readonly _state = live<{ current: string[] }>({ current: [] });
-
-  constructor(initial: string[] = []) {
+  private readonly _map = new Map<string, Atom.Writable<Attention>>();
+  private readonly _currentAtom: Atom.Writable<string[]>;
+
+  constructor(
+    private readonly _registry: Registry.Registry,
+    initial: string[] = [],
+  ) {
+    this._currentAtom = Atom.make<string[]>([]).pipe(Atom.keepAlive);
     if (initial.length > 0) {
       this.update(initial);
     }
   }
 
   /**
-   * Currently attended element.
-   *
-   * @reactive
+   * Atom for the currently attended element IDs.
+   */
+  get current(): Atom.Atom<string[]> {
+    return this._currentAtom;
+  }
+
+  /**
+   * Gets the currently attended element IDs.
+   */
+  getCurrent(): readonly string[] {
+    return this._registry.get(this._currentAtom);
+  }
+
+  /**
+   * Subscribe to changes in the current attention IDs.
    */
-  get current(): Live<readonly string[]> {
-    return this._state.current;
+  subscribeCurrent(cb: (current: readonly string[]) => void): () => void {
+    this._registry.get(this._currentAtom);
+    return this._registry.subscribe(this._currentAtom, () => {
+      cb(this._registry.get(this._currentAtom));
+    });
   }
 
   /**
-   * All attention paths.
+   * All tracked qualified IDs.
    */
-  keys(): string[][] {
+  keys(): string[] {
     return Array.from(this._map.keys());
   }
 
   /**
-   * Get the attention state for a given path.
+   * Get the attention state for a given qualified ID.
    */
-  get(key: string[]): Live<Attention> {
-    const object = this._map.get(key);
-    if (object) {
-      return object;
+  get(id: string): Attention {
+    const atom = this._getAtom(id);
+    return this._registry.get(atom);
+  }
+
+  /**
+   * Subscribe to changes in the attention state for a given qualified ID.
+   */
+  subscribe(id: string, cb: (attention: Attention) => void): () => void {
+    const atom = this._getAtom(id);
+    this._registry.get(atom);
+    return this._registry.subscribe(atom, () => {
+      cb(this._registry.get(atom));
+    });
+  }
+
+  private _getAtom(id: string): Atom.Writable<Attention> {
+    const existing = this._map.get(id);
+    if (existing) {
+      return existing;
     }
 
-    const newObject = live(AttentionSchema, { hasAttention: false, isAncestor: false, isRelated: false });
-    this._map.set(key, newObject);
-    return newObject;
+    const newAtom = Atom.make<Attention>({ hasAttention: false, isAncestor: false, isRelated: false }).pipe(
+      Atom.keepAlive,
+    );
+    this._map.set(id, newAtom);
+    return newAtom;
   }
 
   /**
    * Update the currently attended element.
+   * Takes the array of qualified IDs collected from the DOM; the first element is the primary attended item.
+   * Ancestry is derived from the progressive prefixes of the primary ID.
+   * Relatedness is derived from the segment ID: any tracked key whose last `/` segment matches the
+   * attended ID's segment ID is marked `isRelated`. Additionally, if the primary ID is a linked segment
+   * (starts with `~`), its immediate parent gets `isRelated` alongside `isAncestor`.
    *
    * @internal
    */
-  update(nextKey: string[]): void {
-    const currentKey = untracked(() => this.current);
-    const currentRelatedTo = currentKey[0];
-    const nextRelatedTo = nextKey[0];
+  update(nextIds: string[]): void {
+    const primaryId = nextIds[0];
+    if (!primaryId) {
+      return;
+    }
 
-    // Ensure related attention object is initialized.
-    this.get([nextRelatedTo]);
+    const currentIds = this.getCurrent();
+    const prevPrimaryId = currentIds[0];
+    // Clear previous attention state: ancestors, primary, and related keys.
+    if (prevPrimaryId) {
+      const prevPrefixes = expandAttendableId(prevPrimaryId);
+      for (const prefix of prevPrefixes) {
+        this._set(prefix, {});
+      }
+      const prevSegmentId = getSegmentId(prevPrimaryId);
+      for (const key of this.keys()) {
+        if (getSegmentId(key) === prevSegmentId) {
+          this._set(key, {});
+        }
+      }
+    }
 
-    const currentRelatedKeys = this.keys().filter((key) => key[0] === currentRelatedTo);
-    const nextRelatedKeys = this.keys().filter(
-      (key) => key[0] === nextRelatedTo && stringKey(key) !== stringKey(nextKey),
-    );
-    const prevRelatedKeys = currentRelatedKeys.filter(
-      (curr) => !nextRelatedKeys.find((next) => stringKey(curr) === stringKey(next)),
-    );
+    this._registry.set(this._currentAtom, nextIds);
 
-    const currentAncestorKeys = currentKey.slice(1).map((_, i) => currentKey.slice(i + 1, currentKey.length));
-    const nextAncestorKeys = nextKey.slice(1).map((_, i) => nextKey.slice(i + 1, nextKey.length));
-    const prevAncestorKeys = currentAncestorKeys.filter(
-      (curr) => !nextAncestorKeys.find((next) => stringKey(curr) === stringKey(next)),
-    );
+    // Set ancestors and primary.
+    const prefixes = expandAttendableId(primaryId);
+    const prefixSet = new Set(prefixes);
+    const linkedParent = isLinkedSegment(primaryId) ? getParentId(primaryId) : undefined;
+
+    for (const prefix of prefixes) {
+      if (prefix === primaryId) {
+        this._set(prefix, { hasAttention: true });
+      } else if (prefix === linkedParent) {
+        this._set(prefix, { isAncestor: true, isRelated: true });
+      } else {
+        this._set(prefix, { isAncestor: true });
+      }
+    }
 
-    this._state.current = nextKey;
-    prevRelatedKeys.forEach((key) => this._set(key, {}));
-    prevAncestorKeys.forEach((key) => this._set(key, {}));
-    nextRelatedKeys.forEach((key) => this._set(key, { isRelated: true }));
-    nextAncestorKeys.forEach((key) => this._set(key, { isAncestor: true }));
-    this._set(nextKey, { hasAttention: true });
+    // Set related keys: any tracked key sharing the same segment ID.
+    const segmentId = getSegmentId(primaryId);
+    for (const key of this.keys()) {
+      if (!prefixSet.has(key) && getSegmentId(key) === segmentId) {
+        this._set(key, { isRelated: true });
+      }
+    }
   }
 
-  private _set(key: string[], attention: Partial<Attention>): void {
-    const object = this.get(key);
-    object.hasAttention = attention.hasAttention ?? false;
-    object.isAncestor = attention.isAncestor ?? false;
-    object.isRelated = attention.isRelated ?? false;
+  private _set(id: string, attention: Partial<Attention>): void {
+    const atom = this._getAtom(id);
+    this._registry.set(atom, {
+      hasAttention: attention.hasAttention ?? false,
+      isAncestor: attention.isAncestor ?? false,
+      isRelated: attention.isRelated ?? false,
+    });
   }
 }
 
 /**
- * Accumulates all attendable id’s between the element provided and the root, inclusive.
+ * Accumulates all attendable IDs between the element provided and the root, inclusive.
+ * Each `data-attendable-id` value is treated as a single qualified ID (no splitting).
  */
 export const getAttendables = (selector: string, cursor: Element, acc: string[] = []): string[] => {
   // Find the closest element with `data-attendable-id`, if any; start from cursor and move up the DOM tree.
@@ -130,8 +173,7 @@ export const getAttendables = (selector: string, cursor: Element, acc: string[]
         return getAttendables(selector, trigger, acc);
       }
     } else {
-      acc.push(...attendableId.split(ATTENDABLE_PATH_SEPARATOR));
-      // TODO: Attempt tail recursion.
+      acc.push(attendableId);
       return !closestAttendable.parentElement ? acc : getAttendables(selector, closestAttendable.parentElement, acc);
     }
   }
@@ -142,3 +184,62 @@ export const getAttendables = (selector: string, cursor: Element, acc: string[]
 export type AttendableId = { attendableId?: string };
 
 export type Related = { related?: boolean };
+
+/**
+ * Prefix for linked segments. A linked segment's attention state is shared with its parent:
+ * when a linked node has attention, the parent is marked as both ancestor and related.
+ */
+const LINKED_PREFIX = '~';
+
+/**
+ * Decompose a qualified graph ID into progressive prefixes for ancestry tracking.
+ * e.g. `root/a/b/c` yields `['root', 'root/a', 'root/a/b', 'root/a/b/c']`.
+ */
+export const expandAttendableId = (qualifiedId: string): string[] => {
+  const segments = qualifiedId.split('/');
+  return segments.map((_, index) => segments.slice(0, index + 1).join('/'));
+};
+
+/**
+ * Whether the last segment of a qualified ID is a linked segment (starts with `~`).
+ * Linked segments share their attention state with the parent node.
+ */
+export const isLinkedSegment = (qualifiedId: string): boolean => {
+  const lastSegment = qualifiedId.split('/').pop() ?? '';
+  return lastSegment.startsWith(LINKED_PREFIX);
+};
+
+/**
+ * Build a linked segment ID from a variant name (e.g., `'settings'` -> `'~settings'`).
+ * Nodes identified by linked segments share their attention state with the parent node.
+ */
+export const linkedSegment = (variant: string): string => `${LINKED_PREFIX}${variant}`;
+
+/**
+ * Extract the variant name from the last segment of a qualified ID, stripping the linked prefix.
+ * e.g. `'root/space/obj/~settings'` -> `'settings'`.
+ * If the segment is not linked (no `~` prefix), returns the segment as-is.
+ */
+export const getLinkedVariant = (qualifiedId: string): string => {
+  const lastSegment = qualifiedId.split('/').pop() ?? '';
+  return lastSegment.startsWith(LINKED_PREFIX) ? lastSegment.slice(LINKED_PREFIX.length) : lastSegment;
+};
+
+/**
+ * Get the parent qualified ID (everything before the last `/` segment).
+ */
+export const getParentId = (qualifiedId: string | undefined): string | undefined => {
+  if (!qualifiedId) {
+    return undefined;
+  }
+
+  const lastSlash = qualifiedId.lastIndexOf('/');
+  return lastSlash > 0 ? qualifiedId.slice(0, lastSlash) : undefined;
+};
+
+/**
+ * Extract the segment ID (last segment) of a qualified ID.
+ */
+export const getSegmentId = (qualifiedId: string): string => {
+  return qualifiedId.split('/').pop() ?? qualifiedId;
+};