add tangible configuration interface and internal model for tangible configuration

src/__tests__/integration/tangible-cascade.test.tsx

@@ -0,0 +1,406 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { useWorkspaceStore } from "../../stores/workspaceStore";
+import { useTimelineStore } from "../../stores/timelineStore";
+import { useGraphStore } from "../../stores/graphStore";
+import { resetWorkspaceStore } from "../../test-utils/test-helpers";
+import type { LabelConfig } from "../../types";
+
+describe("Tangible Cascade Cleanup Integration Tests", () => {
+  let documentId: string;
+
+  beforeEach(() => {
+    localStorage.clear();
+    resetWorkspaceStore();
+    documentId = useWorkspaceStore.getState().createDocument("Test Doc");
+  });
+
+  describe("Label deletion cascade", () => {
+    it("should remove deleted label from tangible filterLabels", () => {
+      const { addLabelToDocument, deleteLabelFromDocument } =
+        useWorkspaceStore.getState();
+
+      // Add labels
+      const label1: LabelConfig = {
+        id: "label-1",
+        name: "Label 1",
+        color: "#000",
+        appliesTo: "both",
+      };
+      const label2: LabelConfig = {
+        id: "label-2",
+        name: "Label 2",
+        color: "#111",
+        appliesTo: "both",
+      };
+
+      addLabelToDocument(documentId, label1);
+      addLabelToDocument(documentId, label2);
+
+      // Add tangible with both labels
+      const { addTangibleToDocument } = useWorkspaceStore.getState();
+      addTangibleToDocument(documentId, {
+        id: "tangible-1",
+        name: "Filter Tangible",
+        mode: "filter",
+        filterLabels: ["label-1", "label-2"],
+      });
+
+      // Delete label-1
+      deleteLabelFromDocument(documentId, "label-1");
+
+      // Check tangible only has label-2
+      const doc = useWorkspaceStore.getState().documents.get(documentId);
+      const tangible = doc?.tangibles?.[0];
+
+      expect(tangible?.filterLabels).toEqual(["label-2"]);
+    });
+
+    it("should not delete tangible when label is removed from filterLabels", () => {
+      const { addLabelToDocument, deleteLabelFromDocument } =
+        useWorkspaceStore.getState();
+
+      addLabelToDocument(documentId, {
+        id: "label-1",
+        name: "Label 1",
+        color: "#000",
+        appliesTo: "both",
+      });
+
+      const { addTangibleToDocument } = useWorkspaceStore.getState();
+      addTangibleToDocument(documentId, {
+        id: "tangible-1",
+        name: "Filter Tangible",
+        mode: "filter",
+        filterLabels: ["label-1"],
+      });
+
+      deleteLabelFromDocument(documentId, "label-1");
+
+      const doc = useWorkspaceStore.getState().documents.get(documentId);
+      expect(doc?.tangibles).toHaveLength(1);
+      expect(doc?.tangibles?.[0].filterLabels).toEqual([]);
+    });
+
+    it("should not affect state mode tangibles when label is deleted", () => {
+      const { addLabelToDocument, deleteLabelFromDocument } =
+        useWorkspaceStore.getState();
+
+      addLabelToDocument(documentId, {
+        id: "label-1",
+        name: "Label 1",
+        color: "#000",
+        appliesTo: "both",
+      });
+
+      const timelineStore = useTimelineStore.getState();
+      const stateId = timelineStore.createState("Test State", undefined, false);
+
+      const { addTangibleToDocument } = useWorkspaceStore.getState();
+      addTangibleToDocument(documentId, {
+        id: "tangible-1",
+        name: "State Tangible",
+        mode: "state",
+        stateId: stateId,
+      });
+
+      deleteLabelFromDocument(documentId, "label-1");
+
+      const doc = useWorkspaceStore.getState().documents.get(documentId);
+      expect(doc?.tangibles).toHaveLength(1);
+      expect(doc?.tangibles?.[0].mode).toBe("state");
+      expect(doc?.tangibles?.[0].stateId).toBe(stateId);
+    });
+  });
+
+  describe("State deletion cascade", () => {
+    it("should delete tangible when referenced state is deleted", () => {
+      const timelineStore = useTimelineStore.getState();
+
+      // Create a new state
+      const stateId = timelineStore.createState("Test State", undefined, false);
+
+      // Add tangible referencing this state
+      const { addTangibleToDocument } = useWorkspaceStore.getState();
+      addTangibleToDocument(documentId, {
+        id: "tangible-1",
+        name: "State Tangible",
+        mode: "state",
+        stateId: stateId,
+      });
+
+      // Verify tangible exists
+      let doc = useWorkspaceStore.getState().documents.get(documentId);
+      expect(doc?.tangibles).toHaveLength(1);
+
+      // Switch to root state (can't delete current state)
+      const timeline = timelineStore.timelines.get(documentId);
+      timelineStore.switchToState(timeline!.rootStateId);
+
+      // Delete the state
+      timelineStore.deleteState(stateId);
+
+      // Tangible should be deleted
+      doc = useWorkspaceStore.getState().documents.get(documentId);
+      expect(doc?.tangibles).toHaveLength(0);
+    });
+
+    it("should delete stateDial tangibles when state is deleted", () => {
+      const timelineStore = useTimelineStore.getState();
+
+      const stateId = timelineStore.createState("Dial State", undefined, false);
+
+      const { addTangibleToDocument } = useWorkspaceStore.getState();
+      addTangibleToDocument(documentId, {
+        id: "tangible-1",
+        name: "Dial Tangible",
+        mode: "stateDial",
+        stateId: stateId,
+      });
+
+      const timeline = timelineStore.timelines.get(documentId);
+      timelineStore.switchToState(timeline!.rootStateId);
+      timelineStore.deleteState(stateId);
+
+      const doc = useWorkspaceStore.getState().documents.get(documentId);
+      expect(doc?.tangibles).toHaveLength(0);
+    });
+
+    it("should not delete filter mode tangibles when state is deleted", () => {
+      const timelineStore = useTimelineStore.getState();
+
+      const stateId = timelineStore.createState("Test State", undefined, false);
+
+      const { addLabelToDocument, addTangibleToDocument } =
+        useWorkspaceStore.getState();
+
+      addLabelToDocument(documentId, {
+        id: "label-1",
+        name: "Label 1",
+        color: "#000",
+        appliesTo: "both",
+      });
+
+      addTangibleToDocument(documentId, {
+        id: "tangible-1",
+        name: "Filter Tangible",
+        mode: "filter",
+        filterLabels: ["label-1"],
+      });
+
+      const timeline = timelineStore.timelines.get(documentId);
+      timelineStore.switchToState(timeline!.rootStateId);
+      timelineStore.deleteState(stateId);
+
+      const doc = useWorkspaceStore.getState().documents.get(documentId);
+      expect(doc?.tangibles).toHaveLength(1);
+    });
+
+    it("should handle multiple tangibles referencing same state", () => {
+      const timelineStore = useTimelineStore.getState();
+
+      const stateId = timelineStore.createState(
+        "Shared State",
+        undefined,
+        false,
+      );
+
+      const { addTangibleToDocument } = useWorkspaceStore.getState();
+      addTangibleToDocument(documentId, {
+        name: "State Tangible 1",
+        mode: "state",
+        stateId: stateId,
+        id: "", // Placeholder, will be auto-generated
+      });
+      addTangibleToDocument(documentId, {
+        name: "State Tangible 2",
+        mode: "state",
+        stateId: stateId,
+        id: "", // Placeholder, will be auto-generated
+      });
+      addTangibleToDocument(documentId, {
+        name: "Different State",
+        mode: "state",
+        stateId: "other-state",
+        id: "", // Placeholder, will be auto-generated
+      });
+
+      const timeline = timelineStore.timelines.get(documentId);
+      timelineStore.switchToState(timeline!.rootStateId);
+      timelineStore.deleteState(stateId);
+
+      const doc = useWorkspaceStore.getState().documents.get(documentId);
+      // Only tangible with ID 'different-state' (auto-generated from name) should remain
+      expect(doc?.tangibles).toHaveLength(1);
+    });
+  });
+
+  describe("Document loading and persistence", () => {
+    it("should sync tangibles to graphStore when added to active document", () => {
+      const { addTangibleToDocument, addLabelToDocument } =
+        useWorkspaceStore.getState();
+
+      // Add label first (required for filter mode)
+      addLabelToDocument(documentId, {
+        id: "label-1",
+        name: "Label 1",
+        color: "#000",
+        appliesTo: "both",
+      });
+
+      // Add tangibles to the active document
+      addTangibleToDocument(documentId, {
+        name: "Test Tangible 1",
+        mode: "filter",
+        filterLabels: ["label-1"],
+        hardwareId: "token-001",
+        id: "",
+      });
+      addTangibleToDocument(documentId, {
+        name: "Test Tangible 2",
+        mode: "filter",
+        filterLabels: ["label-1"],
+        hardwareId: "token-002",
+        id: "",
+      });
+
+      // Tangibles should be in graphStore (synced by addTangibleToDocument)
+      const graphTangibles = useGraphStore.getState().tangibles;
+      expect(graphTangibles).toHaveLength(2);
+      expect(graphTangibles[0].name).toBe("Test Tangible 1");
+      expect(graphTangibles[1].name).toBe("Test Tangible 2");
+    });
+
+    it("should persist tangibles in document storage", () => {
+      const { addTangibleToDocument, addLabelToDocument, saveDocument } =
+        useWorkspaceStore.getState();
+
+      // Add label first (required for filter mode)
+      addLabelToDocument(documentId, {
+        id: "label-1",
+        name: "Label 1",
+        color: "#000",
+        appliesTo: "both",
+      });
+
+      // Add tangible
+      addTangibleToDocument(documentId, {
+        name: "Persistent Tangible",
+        mode: "filter",
+        filterLabels: ["label-1"],
+        hardwareId: "token-persistent",
+        id: "",
+      });
+
+      // Save document (though addTangibleToDocument already saves to storage)
+      saveDocument(documentId);
+
+      // Verify tangible is persisted in document
+      const doc = useWorkspaceStore.getState().documents.get(documentId);
+      expect(doc?.tangibles).toHaveLength(1);
+      expect(doc?.tangibles?.[0].hardwareId).toBe("token-persistent");
+      expect(doc?.tangibles?.[0].name).toBe("Persistent Tangible");
+
+      // Verify tangible is also in graphStore (synced by addTangibleToDocument)
+      const graphTangibles = useGraphStore.getState().tangibles;
+      expect(graphTangibles).toHaveLength(1);
+      expect(graphTangibles[0].hardwareId).toBe("token-persistent");
+    });
+
+    it("should mark document as dirty when tangible is added", () => {
+      const { addTangibleToDocument, addLabelToDocument } =
+        useWorkspaceStore.getState();
+
+      // Add label first
+      addLabelToDocument(documentId, {
+        id: "label-1",
+        name: "Label 1",
+        color: "#000",
+        appliesTo: "both",
+      });
+
+      // Clear dirty flag set by label addition
+      const metadata = useWorkspaceStore
+        .getState()
+        .documentMetadata.get(documentId);
+      if (metadata) {
+        metadata.isDirty = false;
+      }
+
+      // Add tangible
+      addTangibleToDocument(documentId, {
+        name: "Test Tangible",
+        mode: "filter",
+        filterLabels: ["label-1"],
+        id: "",
+      });
+
+      // Document should be marked as dirty
+      const updatedMetadata = useWorkspaceStore
+        .getState()
+        .documentMetadata.get(documentId);
+      expect(updatedMetadata?.isDirty).toBe(true);
+    });
+  });
+
+  describe("Cross-store synchronization", () => {
+    it("should sync tangibles to graphStore when label is deleted", () => {
+      const {
+        addLabelToDocument,
+        deleteLabelFromDocument,
+        addTangibleToDocument,
+      } = useWorkspaceStore.getState();
+
+      addLabelToDocument(documentId, {
+        id: "label-1",
+        name: "Label 1",
+        color: "#000",
+        appliesTo: "both",
+      });
+
+      addTangibleToDocument(documentId, {
+        id: "tangible-1",
+        name: "Filter Tangible",
+        mode: "filter",
+        filterLabels: ["label-1"],
+      });
+
+      // Before deletion
+      let graphState = useGraphStore.getState();
+      expect(graphState.tangibles[0].filterLabels).toEqual(["label-1"]);
+
+      // Delete label
+      deleteLabelFromDocument(documentId, "label-1");
+
+      // After deletion - graphStore should be synced
+      graphState = useGraphStore.getState();
+      expect(graphState.tangibles[0].filterLabels).toEqual([]);
+    });
+
+    it("should remove tangibles from graphStore when state is deleted", () => {
+      const timelineStore = useTimelineStore.getState();
+      const { addTangibleToDocument } = useWorkspaceStore.getState();
+
+      const stateId = timelineStore.createState("Test State", undefined, false);
+
+      addTangibleToDocument(documentId, {
+        id: "tangible-1",
+        name: "State Tangible",
+        mode: "state",
+        stateId: stateId,
+      });
+
+      // Before deletion
+      let graphState = useGraphStore.getState();
+      expect(graphState.tangibles).toHaveLength(1);
+
+      // Delete state
+      const timeline = timelineStore.timelines.get(documentId);
+      timelineStore.switchToState(timeline!.rootStateId);
+      timelineStore.deleteState(stateId);
+
+      // After deletion - graphStore should be synced
+      graphState = useGraphStore.getState();
+      expect(graphState.tangibles).toHaveLength(0);
+    });
+  });
+});

src/components/Config/EditTangibleInline.tsx

@@ -0,0 +1,129 @@
+import { useState, useEffect, KeyboardEvent } from 'react';
+import SaveIcon from '@mui/icons-material/Save';
+import TangibleForm from './TangibleForm';
+import type { TangibleConfig, TangibleMode, LabelConfig, ConstellationState } from '../../types';
+
+interface Props {
+  tangible: TangibleConfig;
+  labels: LabelConfig[];
+  states: ConstellationState[];
+  onSave: (
+    id: string,
+    updates: {
+      name: string;
+      mode: TangibleMode;
+      description?: string;
+      hardwareId?: string;
+      filterLabels?: string[];
+      stateId?: string;
+    }
+  ) => void;
+  onCancel: () => void;
+}
+
+const EditTangibleInline = ({ tangible, labels, states, onSave, onCancel }: Props) => {
+  const [name, setName] = useState('');
+  const [mode, setMode] = useState<TangibleMode>('filter');
+  const [description, setDescription] = useState('');
+  const [hardwareId, setHardwareId] = useState('');
+  const [filterLabels, setFilterLabels] = useState<string[]>([]);
+  const [stateId, setStateId] = useState('');
+
+  // Sync state with tangible prop
+  useEffect(() => {
+    if (tangible) {
+      setName(tangible.name);
+      setMode(tangible.mode);
+      setDescription(tangible.description || '');
+      setHardwareId(tangible.hardwareId || '');
+      setFilterLabels(tangible.filterLabels || []);
+      setStateId(tangible.stateId || '');
+    }
+  }, [tangible]);
+
+  const handleSave = () => {
+    if (!name.trim()) return;
+
+    // Validate mode-specific fields
+    if (mode === 'filter' && filterLabels.length === 0) {
+      alert('Filter mode requires at least one label');
+      return;
+    }
+    if ((mode === 'state' || mode === 'stateDial') && !stateId) {
+      alert('State mode requires a state selection');
+      return;
+    }
+
+    onSave(tangible.id, {
+      name: name.trim(),
+      mode,
+      description: description.trim() || undefined,
+      hardwareId: hardwareId.trim() || undefined,
+      filterLabels: mode === 'filter' ? filterLabels : undefined,
+      stateId: (mode === 'state' || mode === 'stateDial') ? stateId : undefined,
+    });
+  };
+
+  const handleKeyDown = (e: KeyboardEvent) => {
+    if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
+      e.preventDefault();
+      handleSave();
+    } else if (e.key === 'Escape') {
+      e.preventDefault();
+      onCancel();
+    }
+  };
+
+  return (
+    <div className="flex flex-col min-h-full" onKeyDown={handleKeyDown}>
+      {/* Form Fields */}
+      <div className="flex-1 mb-6">
+        <TangibleForm
+          name={name}
+          mode={mode}
+          description={description}
+          hardwareId={hardwareId}
+          filterLabels={filterLabels}
+          stateId={stateId}
+          labels={labels}
+          states={states}
+          onNameChange={setName}
+          onModeChange={setMode}
+          onDescriptionChange={setDescription}
+          onHardwareIdChange={setHardwareId}
+          onFilterLabelsChange={setFilterLabels}
+          onStateIdChange={setStateId}
+        />
+      </div>
+
+      {/* Actions */}
+      <div className="pt-6 space-y-3">
+        <div className="flex gap-3">
+          <button
+            onClick={onCancel}
+            className="flex-1 px-6 py-3 text-sm font-medium text-gray-700 bg-gray-100 rounded-md hover:bg-gray-200 transition-colors focus:outline-none focus:ring-2 focus:ring-blue-500"
+          >
+            Cancel
+          </button>
+          <button
+            onClick={handleSave}
+            className="flex-1 px-6 py-3 text-sm font-medium text-white bg-blue-600 rounded-md hover:bg-blue-700 transition-colors focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 flex items-center justify-center gap-2"
+          >
+            <SaveIcon fontSize="small" />
+            Save Changes
+          </button>
+        </div>
+
+        {/* Keyboard Shortcut Hint */}
+        <div className="text-xs text-gray-500 text-center">
+          <kbd className="px-1.5 py-0.5 bg-gray-100 border border-gray-300 rounded text-xs">
+            {navigator.platform.includes('Mac') ? 'Cmd' : 'Ctrl'}+Enter
+          </kbd>{' '}
+          to save, <kbd className="px-1.5 py-0.5 bg-gray-100 border border-gray-300 rounded text-xs">Esc</kbd> to cancel
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default EditTangibleInline;

src/components/Config/QuickAddTangibleForm.tsx

@@ -0,0 +1,117 @@
+import { useState, useRef, KeyboardEvent } from 'react';
+import TangibleForm from './TangibleForm';
+import type { TangibleMode, LabelConfig, ConstellationState } from '../../types';
+
+interface Props {
+  labels: LabelConfig[];
+  states: ConstellationState[];
+  onAdd: (tangible: {
+    name: string;
+    mode: TangibleMode;
+    description: string;
+    hardwareId?: string;
+    filterLabels?: string[];
+    stateId?: string;
+  }) => void;
+}
+
+const QuickAddTangibleForm = ({ labels, states, onAdd }: Props) => {
+  const [name, setName] = useState('');
+  const [hardwareId, setHardwareId] = useState('');
+  const [mode, setMode] = useState<TangibleMode>('filter');
+  const [description, setDescription] = useState('');
+  const [filterLabels, setFilterLabels] = useState<string[]>([]);
+  const [stateId, setStateId] = useState('');
+
+  const nameInputRef = useRef<HTMLInputElement>(null);
+
+  const handleSubmit = () => {
+    if (!name.trim()) {
+      nameInputRef.current?.focus();
+      return;
+    }
+
+    // Validate mode-specific fields
+    if (mode === 'filter' && filterLabels.length === 0) {
+      alert('Filter mode requires at least one label');
+      return;
+    }
+    if ((mode === 'state' || mode === 'stateDial') && !stateId) {
+      alert('State mode requires a state selection');
+      return;
+    }
+
+    onAdd({
+      name: name.trim(),
+      mode,
+      description,
+      hardwareId: hardwareId.trim() || undefined,
+      filterLabels: mode === 'filter' ? filterLabels : undefined,
+      stateId: (mode === 'state' || mode === 'stateDial') ? stateId : undefined,
+    });
+
+    // Reset form
+    setName('');
+    setHardwareId('');
+    setMode('filter');
+    setDescription('');
+    setFilterLabels([]);
+    setStateId('');
+
+    nameInputRef.current?.focus();
+  };
+
+  const handleKeyDown = (e: KeyboardEvent) => {
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault();
+      handleSubmit();
+    } else if (e.key === 'Escape') {
+      e.preventDefault();
+      setName('');
+      setHardwareId('');
+      setMode('filter');
+      setDescription('');
+      setFilterLabels([]);
+      setStateId('');
+      nameInputRef.current?.blur();
+    }
+  };
+
+  return (
+    <div className="space-y-3" onKeyDown={handleKeyDown}>
+      <TangibleForm
+        name={name}
+        hardwareId={hardwareId}
+        mode={mode}
+        description={description}
+        filterLabels={filterLabels}
+        stateId={stateId}
+        labels={labels}
+        states={states}
+        onNameChange={setName}
+        onHardwareIdChange={setHardwareId}
+        onModeChange={setMode}
+        onDescriptionChange={setDescription}
+        onFilterLabelsChange={setFilterLabels}
+        onStateIdChange={setStateId}
+      />
+
+      <button
+        onClick={handleSubmit}
+        className="w-full px-4 py-2 bg-blue-600 text-white text-sm font-medium rounded-md hover:bg-blue-700 transition-colors focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2"
+        aria-label="Add tangible"
+      >
+        Add Tangible
+      </button>
+
+      {/* Keyboard Shortcuts Hint */}
+      {name && (
+        <div className="text-xs text-gray-500 italic">
+          Press Enter to add, Escape to cancel
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default QuickAddTangibleForm;

src/components/Config/TangibleConfig.tsx

@@ -0,0 +1,204 @@
+import { useState, useEffect, useMemo } from 'react';
+import { useGraphWithHistory } from '../../hooks/useGraphWithHistory';
+import { useConfirm } from '../../hooks/useConfirm';
+import { useToastStore } from '../../stores/toastStore';
+import { useTimelineStore } from '../../stores/timelineStore';
+import QuickAddTangibleForm from './QuickAddTangibleForm';
+import TangibleManagementList from './TangibleManagementList';
+import EditTangibleInline from './EditTangibleInline';
+import type { TangibleConfig as TangibleConfigType, TangibleMode } from '../../types';
+
+interface Props {
+  isOpen: boolean;
+  onClose: () => void;
+  initialEditingTangibleId?: string | null;
+}
+
+const TangibleConfigModal = ({ isOpen, onClose, initialEditingTangibleId }: Props) => {
+  const { tangibles, labels, addTangible, updateTangible, deleteTangible } = useGraphWithHistory();
+  const { confirm, ConfirmDialogComponent } = useConfirm();
+  const { showToast } = useToastStore();
+  const { getAllStates } = useTimelineStore();
+
+  const [editingTangible, setEditingTangible] = useState<TangibleConfigType | null>(null);
+
+  // Get all available states for state mode
+  const availableStates = useMemo(() => getAllStates(), [getAllStates]);
+
+  // Set editing tangible when initialEditingTangibleId changes
+  useEffect(() => {
+    if (initialEditingTangibleId && isOpen) {
+      const tangibleToEdit = tangibles.find((t) => t.id === initialEditingTangibleId);
+      if (tangibleToEdit) {
+        setEditingTangible(tangibleToEdit);
+      }
+    } else if (!isOpen) {
+      setEditingTangible(null);
+    }
+  }, [initialEditingTangibleId, isOpen, tangibles]);
+
+  const handleAddTangible = (tangible: {
+    name: string;
+    mode: TangibleMode;
+    description: string;
+    hardwareId?: string;
+    filterLabels?: string[];
+    stateId?: string;
+  }) => {
+    // Validate mode-specific fields
+    if (tangible.mode === 'filter' && (!tangible.filterLabels || tangible.filterLabels.length === 0)) {
+      showToast('Filter mode requires at least one label', 'error');
+      return;
+    }
+    if ((tangible.mode === 'state' || tangible.mode === 'stateDial') && !tangible.stateId) {
+      showToast('State mode requires a state selection', 'error');
+      return;
+    }
+
+    const newTangible: Omit<TangibleConfigType, 'id'> = {
+      name: tangible.name,
+      mode: tangible.mode,
+      description: tangible.description || undefined,
+      hardwareId: tangible.hardwareId,
+      filterLabels: tangible.filterLabels,
+      stateId: tangible.stateId,
+    };
+
+    addTangible(newTangible as TangibleConfigType);
+    showToast(`Tangible "${tangible.name}" created`, 'success');
+  };
+
+  const handleDeleteTangible = async (id: string) => {
+    const tangible = tangibles.find((t) => t.id === id);
+
+    const confirmed = await confirm({
+      title: 'Delete Tangible',
+      message: 'Are you sure you want to delete this tangible? This action cannot be undone.',
+      confirmLabel: 'Delete',
+      severity: 'danger',
+    });
+
+    if (confirmed) {
+      deleteTangible(id);
+      showToast(`Tangible "${tangible?.name}" deleted`, 'success');
+    }
+  };
+
+  const handleEditTangible = (tangible: TangibleConfigType) => {
+    setEditingTangible(tangible);
+  };
+
+  const handleSaveEdit = (
+    id: string,
+    updates: { name: string; mode: TangibleMode; description?: string; hardwareId?: string; filterLabels?: string[]; stateId?: string }
+  ) => {
+    updateTangible(id, updates);
+    setEditingTangible(null);
+    showToast(`Tangible "${updates.name}" updated`, 'success');
+  };
+
+  const handleCancelEdit = () => {
+    setEditingTangible(null);
+  };
+
+  if (!isOpen) return null;
+
+  return (
+    <>
+      {/* Main Modal */}
+      <div className="fixed inset-0 bg-black bg-opacity-50 flex items-center justify-center z-50">
+        <div className="bg-white rounded-lg shadow-xl w-full max-w-5xl max-h-[85vh] overflow-hidden flex flex-col">
+          {/* Header */}
+          <div className="px-6 py-4 border-b border-gray-200">
+            <h2 className="text-xl font-bold text-gray-900">Configure Tangibles</h2>
+            <p className="text-sm text-gray-600 mt-1">
+              Set up physical objects for presentation mode interactions
+            </p>
+          </div>
+
+          {/* Content - Two-Column or Full-Width Edit */}
+          <div className="flex-1 overflow-hidden flex">
+            {editingTangible ? (
+              /* Full-Width Edit Mode */
+              <div className="w-full p-6 overflow-y-auto">
+                <div className="max-w-2xl mx-auto">
+                  <EditTangibleInline
+                    tangible={editingTangible}
+                    labels={labels}
+                    states={availableStates}
+                    onSave={handleSaveEdit}
+                    onCancel={handleCancelEdit}
+                  />
+                </div>
+              </div>
+            ) : (
+              <>
+                {/* Left Column - Quick Add (60%) */}
+                <div className="w-3/5 border-r border-gray-200 p-6 overflow-y-auto">
+                  <div>
+                    <h3 className="text-sm font-semibold text-gray-700 mb-4">
+                      Quick Add Tangible
+                    </h3>
+                    <QuickAddTangibleForm
+                      labels={labels}
+                      states={availableStates}
+                      onAdd={handleAddTangible}
+                    />
+                  </div>
+
+                  {/* Helper Text */}
+                  <div className="mt-6 p-4 bg-blue-50 border border-blue-200 rounded-lg">
+                    <h4 className="text-sm font-semibold text-blue-900 mb-1">About Tangibles</h4>
+                    <ul className="text-xs text-blue-800 space-y-1">
+                      <li>• Tangibles are physical objects used in presentation mode</li>
+                      <li>• Filter mode: activates filters on selected labels</li>
+                      <li>• State mode: switches to a specific timeline state</li>
+                      <li>• Internal IDs are auto-generated from names</li>
+                      <li>• Hardware IDs map configurations to physical tokens/devices</li>
+                      <li>• You can change hardware IDs to swap physical tokens</li>
+                    </ul>
+                  </div>
+                </div>
+
+                {/* Right Column - Management (40%) */}
+                <div className="w-2/5 p-6 overflow-y-auto bg-gray-50">
+                  <div>
+                    <div className="flex items-center justify-between mb-4">
+                      <h3 className="text-sm font-semibold text-gray-700">
+                        Tangibles ({tangibles.length})
+                      </h3>
+                    </div>
+                    <TangibleManagementList
+                      tangibles={tangibles}
+                      labels={labels}
+                      states={availableStates}
+                      onEdit={handleEditTangible}
+                      onDelete={handleDeleteTangible}
+                    />
+                  </div>
+                </div>
+              </>
+            )}
+          </div>
+
+          {/* Footer - Hidden when editing */}
+          {!editingTangible && (
+            <div className="px-6 py-4 border-t border-gray-200 flex justify-end">
+              <button
+                onClick={onClose}
+                className="px-4 py-2 bg-gray-200 text-gray-800 text-sm font-medium rounded-md hover:bg-gray-300 transition-colors focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2"
+              >
+                Done
+              </button>
+            </div>
+          )}
+        </div>
+      </div>
+
+      {/* Confirmation Dialog */}
+      {ConfirmDialogComponent}
+    </>
+  );
+};
+
+export default TangibleConfigModal;

src/components/Config/TangibleForm.tsx

@@ -0,0 +1,180 @@
+import type { TangibleMode, LabelConfig, ConstellationState } from '../../types';
+
+interface Props {
+  name: string;
+  mode: TangibleMode;
+  description: string;
+  hardwareId: string;
+  filterLabels: string[];
+  stateId: string;
+  labels: LabelConfig[];
+  states: ConstellationState[];
+  onNameChange: (value: string) => void;
+  onModeChange: (value: TangibleMode) => void;
+  onDescriptionChange: (value: string) => void;
+  onHardwareIdChange: (value: string) => void;
+  onFilterLabelsChange: (value: string[]) => void;
+  onStateIdChange: (value: string) => void;
+}
+
+const TangibleForm = ({
+  name,
+  mode,
+  description,
+  hardwareId,
+  filterLabels,
+  stateId,
+  labels,
+  states,
+  onNameChange,
+  onModeChange,
+  onDescriptionChange,
+  onHardwareIdChange,
+  onFilterLabelsChange,
+  onStateIdChange,
+}: Props) => {
+  return (
+    <div className="space-y-3">
+      <div>
+        <label className="block text-xs font-medium text-gray-700 mb-1">
+          Name *
+        </label>
+        <input
+          type="text"
+          value={name}
+          onChange={(e) => onNameChange(e.target.value)}
+          placeholder="e.g., Red Block, Filter Card"
+          className="w-full px-3 py-2 border border-gray-300 rounded-md text-sm focus:outline-none focus:ring-2 focus:ring-blue-500"
+        />
+      </div>
+
+      <div>
+        <label className="block text-xs font-medium text-gray-700 mb-1">
+          Hardware ID (optional)
+        </label>
+        <input
+          type="text"
+          value={hardwareId}
+          onChange={(e) => onHardwareIdChange(e.target.value)}
+          placeholder="e.g., token-001, device-a"
+          className="w-full px-3 py-2 border border-gray-300 rounded-md text-sm focus:outline-none focus:ring-2 focus:ring-blue-500"
+        />
+        <p className="text-xs text-gray-500 mt-1">
+          Maps this configuration to a physical token or device
+        </p>
+      </div>
+
+      <div>
+        <label className="block text-xs font-medium text-gray-700 mb-1">
+          Mode *
+        </label>
+        <div className="space-y-2">
+          <label className="flex items-center cursor-pointer">
+            <input
+              type="radio"
+              name="mode"
+              value="filter"
+              checked={mode === 'filter'}
+              onChange={(e) => onModeChange(e.target.value as TangibleMode)}
+              className="mr-2"
+            />
+            <span className="text-sm text-gray-700">Filter mode (activate label filters)</span>
+          </label>
+          <label className="flex items-center cursor-pointer">
+            <input
+              type="radio"
+              name="mode"
+              value="state"
+              checked={mode === 'state'}
+              onChange={(e) => onModeChange(e.target.value as TangibleMode)}
+              className="mr-2"
+            />
+            <span className="text-sm text-gray-700">State mode (switch to timeline state)</span>
+          </label>
+          <label className="flex items-center cursor-pointer">
+            <input
+              type="radio"
+              name="mode"
+              value="stateDial"
+              checked={mode === 'stateDial'}
+              onChange={(e) => onModeChange(e.target.value as TangibleMode)}
+              className="mr-2"
+            />
+            <span className="text-sm text-gray-700">State dial mode (clock-like, deferred)</span>
+          </label>
+        </div>
+      </div>
+
+      {/* Mode-specific fields */}
+      {mode === 'filter' && (
+        <div>
+          <label className="block text-xs font-medium text-gray-700 mb-1">
+            Filter Labels * (select one or more)
+          </label>
+          <div className="border border-gray-300 rounded-md p-2 max-h-40 overflow-y-auto">
+            {labels.length === 0 ? (
+              <p className="text-xs text-gray-500 italic">No labels available</p>
+            ) : (
+              labels.map((label) => (
+                <label key={label.id} className="flex items-center py-1 cursor-pointer">
+                  <input
+                    type="checkbox"
+                    checked={filterLabels.includes(label.id)}
+                    onChange={(e) => {
+                      if (e.target.checked) {
+                        onFilterLabelsChange([...filterLabels, label.id]);
+                      } else {
+                        onFilterLabelsChange(filterLabels.filter((id) => id !== label.id));
+                      }
+                    }}
+                    className="mr-2"
+                  />
+                  <span
+                    className="w-3 h-3 rounded-full mr-2"
+                    style={{ backgroundColor: label.color }}
+                  />
+                  <span className="text-sm text-gray-700">{label.name}</span>
+                </label>
+              ))
+            )}
+          </div>
+        </div>
+      )}
+
+      {(mode === 'state' || mode === 'stateDial') && (
+        <div>
+          <label className="block text-xs font-medium text-gray-700 mb-1">
+            Timeline State *
+          </label>
+          <select
+            value={stateId}
+            onChange={(e) => onStateIdChange(e.target.value)}
+            className="w-full px-3 py-2 border border-gray-300 rounded-md text-sm focus:outline-none focus:ring-2 focus:ring-blue-500"
+          >
+            <option value="">Select a state...</option>
+            {states.map((state) => (
+              <option key={state.id} value={state.id}>
+                {state.label}
+              </option>
+            ))}
+          </select>
+        </div>
+      )}
+
+      <div>
+        <label className="block text-xs font-medium text-gray-700 mb-1">
+          Description (optional)
+        </label>
+        <input
+          type="text"
+          value={description}
+          onChange={(e) => onDescriptionChange(e.target.value)}
+          placeholder="Brief description of this tangible"
+          className="w-full px-3 py-2 border border-gray-300 rounded-md text-sm focus:outline-none focus:ring-2 focus:ring-blue-500"
+        />
+      </div>
+    </div>
+  );
+};
+
+export default TangibleForm;

src/components/Config/TangibleManagementList.tsx

@@ -0,0 +1,97 @@
+import DeleteIcon from '@mui/icons-material/Delete';
+import type { TangibleConfig, LabelConfig, ConstellationState } from '../../types';
+
+interface Props {
+  tangibles: TangibleConfig[];
+  labels: LabelConfig[];
+  states: ConstellationState[];
+  onEdit: (tangible: TangibleConfig) => void;
+  onDelete: (id: string) => void;
+}
+
+const TangibleManagementList = ({ tangibles, states, onEdit, onDelete }: Props) => {
+  if (tangibles.length === 0) {
+    return (
+      <div className="text-center py-12 text-gray-500">
+        <p className="text-sm">No tangibles yet.</p>
+        <p className="text-xs mt-1">Add your first tangible above.</p>
+      </div>
+    );
+  }
+
+  const getModeDisplay = (tangible: TangibleConfig) => {
+    switch (tangible.mode) {
+      case 'filter': {
+        const labelCount = tangible.filterLabels?.length || 0;
+        return `Filter (${labelCount} label${labelCount !== 1 ? 's' : ''})`;
+      }
+      case 'state': {
+        const state = states.find(s => s.id === tangible.stateId);
+        return `State: ${state?.label || 'Unknown'}`;
+      }
+      case 'stateDial': {
+        const dialState = states.find(s => s.id === tangible.stateId);
+        return `State Dial: ${dialState?.label || 'Unknown'}`;
+      }
+      default:
+        return tangible.mode;
+    }
+  };
+
+  return (
+    <div className="space-y-2">
+      {tangibles.map((tangible) => (
+        <div
+          key={tangible.id}
+          className="group bg-white border border-gray-200 rounded-lg p-3 hover:border-blue-300 hover:shadow-sm transition-all cursor-pointer"
+          onClick={() => onEdit(tangible)}
+          role="button"
+          tabIndex={0}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter' || e.key === ' ') {
+              e.preventDefault();
+              onEdit(tangible);
+            }
+          }}
+          aria-label={`Edit ${tangible.name}`}
+        >
+          <div className="flex items-start justify-between gap-3">
+            <div className="flex-1 min-w-0">
+              <h4 className="text-sm font-medium text-gray-900 truncate">
+                {tangible.name}
+              </h4>
+              {tangible.hardwareId && (
+                <p className="text-xs text-gray-600 mt-1">
+                  Hardware: <code className="bg-gray-100 px-1 rounded">{tangible.hardwareId}</code>
+                </p>
+              )}
+              <p className="text-xs text-gray-500 mt-1">
+                {getModeDisplay(tangible)}
+              </p>
+              {tangible.description && (
+                <p className="text-xs text-gray-400 mt-1 italic truncate">
+                  {tangible.description}
+                </p>
+              )}
+            </div>
+            <div className="flex gap-1">
+              <button
+                onClick={(e) => {
+                  e.stopPropagation();
+                  onDelete(tangible.id);
+                }}
+                className="p-1.5 text-red-600 hover:bg-red-50 rounded transition-colors focus:outline-none focus:ring-2 focus:ring-red-500"
+                aria-label={`Delete ${tangible.name}`}
+                title="Delete"
+              >
+                <DeleteIcon fontSize="small" />
+              </button>
+            </div>
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+};
+
+export default TangibleManagementList;

src/components/Menu/MenuBar.tsx

@@ -8,6 +8,7 @@ import DocumentManager from '../Workspace/DocumentManager';
 import NodeTypeConfigModal from '../Config/NodeTypeConfig';
 import EdgeTypeConfigModal from '../Config/EdgeTypeConfig';
 import LabelConfigModal from '../Config/LabelConfig';
+import TangibleConfigModal from '../Config/TangibleConfig';
 import BibliographyConfigModal from '../Config/BibliographyConfig';
 import InputDialog from '../Common/InputDialog';
 import { useConfirm } from '../../hooks/useConfirm';
@@ -36,6 +37,7 @@ const MenuBar: React.FC<MenuBarProps> = ({ onOpenHelp, onFitView, onExport }) =>
   const [showNodeConfig, setShowNodeConfig] = useState(false);
   const [showEdgeConfig, setShowEdgeConfig] = useState(false);
   const [showLabelConfig, setShowLabelConfig] = useState(false);
+  const [showTangibleConfig, setShowTangibleConfig] = useState(false);
   const [showBibliographyConfig, setShowBibliographyConfig] = useState(false);
   const [showNewDocDialog, setShowNewDocDialog] = useState(false);
   const [showNewFromTemplateDialog, setShowNewFromTemplateDialog] = useState(false);
@@ -184,6 +186,11 @@ const MenuBar: React.FC<MenuBarProps> = ({ onOpenHelp, onFitView, onExport }) =>
     closeMenu();
   }, [closeMenu]);
 
+  const handleConfigureTangibles = useCallback(() => {
+    setShowTangibleConfig(true);
+    closeMenu();
+  }, [closeMenu]);
+
   const handleManageBibliography = useCallback(() => {
     setShowBibliographyConfig(true);
     closeMenu();
@@ -395,6 +402,12 @@ const MenuBar: React.FC<MenuBarProps> = ({ onOpenHelp, onFitView, onExport }) =>
                 >
                   Configure Labels
                 </button>
+                <button
+                  onClick={handleConfigureTangibles}
+                  className="w-full text-left px-4 py-2 text-sm text-gray-700 hover:bg-gray-100"
+                >
+                  Configure Tangibles
+                </button>
                 <button
                   onClick={handleManageBibliography}
                   className="w-full text-left px-4 py-2 text-sm text-gray-700 hover:bg-gray-100"
@@ -509,6 +522,10 @@ const MenuBar: React.FC<MenuBarProps> = ({ onOpenHelp, onFitView, onExport }) =>
         isOpen={showLabelConfig}
         onClose={() => setShowLabelConfig(false)}
       />
+      <TangibleConfigModal
+        isOpen={showTangibleConfig}
+        onClose={() => setShowTangibleConfig(false)}
+      />
       <BibliographyConfigModal
         isOpen={showBibliographyConfig}
         onClose={() => setShowBibliographyConfig(false)}

src/hooks/useGraphWithHistory.ts

@@ -2,7 +2,7 @@ import { useCallback, useRef, useEffect } from 'react';
 import { useGraphStore } from '../stores/graphStore';
 import { useWorkspaceStore } from '../stores/workspaceStore';
 import { useDocumentHistory } from './useDocumentHistory';
-import type { Actor, Relation, Group, NodeTypeConfig, EdgeTypeConfig, LabelConfig, RelationData, GroupData } from '../types';
+import type { Actor, Relation, Group, NodeTypeConfig, EdgeTypeConfig, LabelConfig, TangibleConfig, RelationData, GroupData } from '../types';
 
 /**
  * useGraphWithHistory Hook
@@ -22,11 +22,12 @@ import type { Actor, Relation, Group, NodeTypeConfig, EdgeTypeConfig, LabelConfi
  * - Group operations: addGroup, updateGroup, deleteGroup, addActorToGroup, removeActorFromGroup
  * - Type operations: addNodeType, updateNodeType, deleteNodeType, addEdgeType, updateEdgeType, deleteEdgeType
  * - Label operations: addLabel, updateLabel, deleteLabel
+ * - Tangible operations: addTangible, updateTangible, deleteTangible
  * - Utility: clearGraph
  *
  * Read-only pass-through operations (no history):
- * - setNodes, setEdges, setGroups, setLabels (used for bulk updates during undo/redo/document loading)
+ * - setNodes, setEdges, setGroups, setLabels, setTangibles (used for bulk updates during undo/redo/document loading)
- * - nodes, edges, groups, nodeTypes, edgeTypes, labels (state access)
+ * - nodes, edges, groups, nodeTypes, edgeTypes, labels, tangibles (state access)
  * - loadGraphState
  *
  * Usage:
@@ -51,6 +52,9 @@ export function useGraphWithHistory() {
   const addLabelToDocument = useWorkspaceStore((state) => state.addLabelToDocument);
   const updateLabelInDocument = useWorkspaceStore((state) => state.updateLabelInDocument);
   const deleteLabelFromDocument = useWorkspaceStore((state) => state.deleteLabelFromDocument);
+  const addTangibleToDocument = useWorkspaceStore((state) => state.addTangibleToDocument);
+  const updateTangibleInDocument = useWorkspaceStore((state) => state.updateTangibleInDocument);
+  const deleteTangibleFromDocument = useWorkspaceStore((state) => state.deleteTangibleFromDocument);
   const { pushToHistory } = useDocumentHistory();
 
   // Track if we're currently restoring from history to prevent recursive history pushes
@@ -339,6 +343,56 @@ export function useGraphWithHistory() {
     [activeDocumentId, graphStore, pushToHistory, deleteLabelFromDocument]
   );
 
+  // Tangible operations
+  const addTangible = useCallback(
+    (tangible: TangibleConfig) => {
+      if (!activeDocumentId) {
+        console.warn('No active document');
+        return;
+      }
+      if (isRestoringRef.current) {
+        graphStore.addTangible(tangible);
+        return;
+      }
+      pushToHistory(`Add Tangible: ${tangible.name}`); // Synchronous push BEFORE mutation
+      addTangibleToDocument(activeDocumentId, tangible);
+    },
+    [activeDocumentId, graphStore, pushToHistory, addTangibleToDocument]
+  );
+
+  const updateTangible = useCallback(
+    (id: string, updates: Partial<Omit<TangibleConfig, 'id'>>) => {
+      if (!activeDocumentId) {
+        console.warn('No active document');
+        return;
+      }
+      if (isRestoringRef.current) {
+        graphStore.updateTangible(id, updates);
+        return;
+      }
+      pushToHistory('Update Tangible'); // Synchronous push BEFORE mutation
+      updateTangibleInDocument(activeDocumentId, id, updates);
+    },
+    [activeDocumentId, graphStore, pushToHistory, updateTangibleInDocument]
+  );
+
+  const deleteTangible = useCallback(
+    (id: string) => {
+      if (!activeDocumentId) {
+        console.warn('No active document');
+        return;
+      }
+      if (isRestoringRef.current) {
+        graphStore.deleteTangible(id);
+        return;
+      }
+      const tangible = graphStore.tangibles.find((t) => t.id === id);
+      pushToHistory(`Delete Tangible: ${tangible?.name || id}`); // Synchronous push BEFORE mutation
+      deleteTangibleFromDocument(activeDocumentId, id);
+    },
+    [activeDocumentId, graphStore, pushToHistory, deleteTangibleFromDocument]
+  );
+
   // Group operations
   const addGroup = useCallback(
     (group: Group) => {
@@ -495,6 +549,9 @@ export function useGraphWithHistory() {
     addLabel,
     updateLabel,
     deleteLabel,
+    addTangible,
+    updateTangible,
+    deleteTangible,
     clearGraph,
 
     // Pass through read-only operations
@@ -504,12 +561,14 @@ export function useGraphWithHistory() {
     nodeTypes: graphStore.nodeTypes,
     edgeTypes: graphStore.edgeTypes,
     labels: graphStore.labels,
+    tangibles: graphStore.tangibles,
     setNodes: graphStore.setNodes,
     setEdges: graphStore.setEdges,
     setGroups: graphStore.setGroups,
     setNodeTypes: graphStore.setNodeTypes,
     setEdgeTypes: graphStore.setEdgeTypes,
     setLabels: graphStore.setLabels,
+    setTangibles: graphStore.setTangibles,
     loadGraphState: graphStore.loadGraphState,
 
     // NOTE: exportToFile and importFromFile have been removed

src/stores/graphStore.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { useGraphStore } from './graphStore';
-import type { Actor, Relation, Group, NodeTypeConfig, EdgeTypeConfig, LabelConfig, NodeShape } from '../types';
+import type { Actor, Relation, Group, NodeTypeConfig, EdgeTypeConfig, LabelConfig, TangibleConfig, NodeShape } from '../types';
 import { MINIMIZED_GROUP_WIDTH, MINIMIZED_GROUP_HEIGHT } from '../constants';
 
 // Helper to create a mock node
@@ -66,6 +66,7 @@ describe('graphStore', () => {
         { id: 'reports-to', label: 'Reports To', color: '#10b981', style: 'solid' },
       ],
       labels: [],
+      tangibles: [],
     });
   });
 
@@ -889,6 +890,203 @@ describe('graphStore', () => {
     });
   });
 
+  describe('Tangible Management', () => {
+    describe('addTangible', () => {
+      it('should add a tangible', () => {
+        const { addTangible } = useGraphStore.getState();
+
+        const tangible: TangibleConfig = {
+          id: 'tangible-1',
+          name: 'Red Block',
+          mode: 'filter',
+          filterLabels: ['label-1'],
+        };
+
+        addTangible(tangible);
+
+        const state = useGraphStore.getState();
+        expect(state.tangibles).toHaveLength(1);
+        expect(state.tangibles[0]).toEqual(tangible);
+      });
+
+      it('should add multiple tangibles', () => {
+        const { addTangible } = useGraphStore.getState();
+
+        addTangible({ id: 't1', name: 'T1', mode: 'filter', filterLabels: [] });
+        addTangible({ id: 't2', name: 'T2', mode: 'state', stateId: 's1' });
+
+        const state = useGraphStore.getState();
+        expect(state.tangibles).toHaveLength(2);
+      });
+    });
+
+    describe('updateTangible', () => {
+      beforeEach(() => {
+        const { addTangible } = useGraphStore.getState();
+        addTangible({
+          id: 'tangible-1',
+          name: 'Original',
+          mode: 'filter',
+          filterLabels: ['label-1'],
+        });
+      });
+
+      it('should update tangible name', () => {
+        const { updateTangible } = useGraphStore.getState();
+
+        updateTangible('tangible-1', { name: 'Updated' });
+
+        const state = useGraphStore.getState();
+        expect(state.tangibles[0].name).toBe('Updated');
+      });
+
+      it('should update tangible mode', () => {
+        const { updateTangible } = useGraphStore.getState();
+
+        updateTangible('tangible-1', {
+          mode: 'state',
+          stateId: 'state-1',
+          filterLabels: undefined,
+        });
+
+        const state = useGraphStore.getState();
+        expect(state.tangibles[0].mode).toBe('state');
+        expect(state.tangibles[0].stateId).toBe('state-1');
+      });
+
+      it('should update tangible description', () => {
+        const { updateTangible } = useGraphStore.getState();
+
+        updateTangible('tangible-1', { description: 'New description' });
+
+        const state = useGraphStore.getState();
+        expect(state.tangibles[0].description).toBe('New description');
+      });
+    });
+
+    describe('deleteTangible', () => {
+      beforeEach(() => {
+        const { addTangible } = useGraphStore.getState();
+        addTangible({ id: 't1', name: 'T1', mode: 'filter', filterLabels: [] });
+        addTangible({ id: 't2', name: 'T2', mode: 'state', stateId: 's1' });
+      });
+
+      it('should delete a tangible', () => {
+        const { deleteTangible } = useGraphStore.getState();
+
+        deleteTangible('t1');
+
+        const state = useGraphStore.getState();
+        expect(state.tangibles).toHaveLength(1);
+        expect(state.tangibles[0].id).toBe('t2');
+      });
+
+      it('should delete correct tangible when multiple exist', () => {
+        const { deleteTangible } = useGraphStore.getState();
+
+        deleteTangible('t2');
+
+        const state = useGraphStore.getState();
+        expect(state.tangibles).toHaveLength(1);
+        expect(state.tangibles[0].id).toBe('t1');
+      });
+    });
+
+    describe('setTangibles', () => {
+      it('should replace all tangibles', () => {
+        const { setTangibles } = useGraphStore.getState();
+        const newTangibles: TangibleConfig[] = [
+          { id: 't1', name: 'T1', mode: 'filter', filterLabels: [] },
+          { id: 't2', name: 'T2', mode: 'state', stateId: 's1' },
+        ];
+
+        setTangibles(newTangibles);
+
+        const state = useGraphStore.getState();
+        expect(state.tangibles).toEqual(newTangibles);
+      });
+
+      it('should clear tangibles when set to empty array', () => {
+        const { addTangible, setTangibles } = useGraphStore.getState();
+        addTangible({ id: 't1', name: 'T1', mode: 'filter', filterLabels: [] });
+
+        setTangibles([]);
+
+        const state = useGraphStore.getState();
+        expect(state.tangibles).toHaveLength(0);
+      });
+    });
+
+    describe('deleteLabel cascade cleanup', () => {
+      beforeEach(() => {
+        const { addLabel, addTangible } = useGraphStore.getState();
+
+        addLabel({ id: 'label-1', name: 'Label 1', color: '#000', appliesTo: 'both' });
+        addLabel({ id: 'label-2', name: 'Label 2', color: '#111', appliesTo: 'both' });
+
+        addTangible({
+          id: 't1',
+          name: 'Filter Both',
+          mode: 'filter',
+          filterLabels: ['label-1', 'label-2'],
+        });
+        addTangible({
+          id: 't2',
+          name: 'Filter One',
+          mode: 'filter',
+          filterLabels: ['label-1'],
+        });
+      });
+
+      it('should remove deleted label from tangible filterLabels', () => {
+        const { deleteLabel } = useGraphStore.getState();
+
+        deleteLabel('label-1');
+
+        const state = useGraphStore.getState();
+        const t1 = state.tangibles.find((t) => t.id === 't1');
+        const t2 = state.tangibles.find((t) => t.id === 't2');
+
+        expect(t1?.filterLabels).toEqual(['label-2']);
+        expect(t2?.filterLabels).toEqual([]);
+      });
+
+      it('should not affect state mode tangibles', () => {
+        const { addTangible, deleteLabel } = useGraphStore.getState();
+
+        addTangible({
+          id: 't3',
+          name: 'State Mode',
+          mode: 'state',
+          stateId: 'state-1',
+        });
+
+        deleteLabel('label-1');
+
+        const state = useGraphStore.getState();
+        const t3 = state.tangibles.find((t) => t.id === 't3');
+
+        expect(t3).toBeDefined();
+        expect(t3?.mode).toBe('state');
+        expect(t3?.stateId).toBe('state-1');
+      });
+
+      it('should handle multiple labels being deleted', () => {
+        const { deleteLabel } = useGraphStore.getState();
+
+        deleteLabel('label-1');
+        deleteLabel('label-2');
+
+        const state = useGraphStore.getState();
+        const t1 = state.tangibles.find((t) => t.id === 't1');
+        const t2 = state.tangibles.find((t) => t.id === 't2');
+
+        expect(t1?.filterLabels).toEqual([]);
+        expect(t2?.filterLabels).toEqual([]);
+      });
+    });
+  });
+
   describe('Utility Operations', () => {
     describe('clearGraph', () => {
       beforeEach(() => {

src/stores/graphStore.ts

@@ -7,6 +7,7 @@ import type {
   NodeTypeConfig,
   EdgeTypeConfig,
   LabelConfig,
+  TangibleConfig,
   RelationData,
   GroupData,
   GraphActions
@@ -34,6 +35,7 @@ interface GraphStore {
   nodeTypes: NodeTypeConfig[];
   edgeTypes: EdgeTypeConfig[];
   labels: LabelConfig[];
+  tangibles: TangibleConfig[];
 }
 
 // Default node types with semantic shape assignments
@@ -60,6 +62,7 @@ const initialState: GraphStore = {
   nodeTypes: defaultNodeTypes,
   edgeTypes: defaultEdgeTypes,
   labels: [],
+  tangibles: [],
 };
 
 export const useGraphStore = create<GraphStore & GraphActions>((set) => ({
@@ -69,6 +72,7 @@ export const useGraphStore = create<GraphStore & GraphActions>((set) => ({
   nodeTypes: initialState.nodeTypes,
   edgeTypes: initialState.edgeTypes,
   labels: initialState.labels,
+  tangibles: initialState.tangibles,
 
   // Node operations
   addNode: (node: Actor) =>
@@ -217,13 +221,48 @@ export const useGraphStore = create<GraphStore & GraphActions>((set) => ({
           : edge.data,
       }));
 
+      // Remove label from tangible filterLabels arrays
+      const updatedTangibles = state.tangibles.map((tangible) => {
+        if (tangible.mode === 'filter' && tangible.filterLabels) {
+          return {
+            ...tangible,
+            filterLabels: tangible.filterLabels.filter((labelId) => labelId !== id),
+          };
+        }
+        return tangible;
+      });
+
       return {
         labels: state.labels.filter((label) => label.id !== id),
         nodes: updatedNodes,
         edges: updatedEdges,
+        tangibles: updatedTangibles,
       };
     }),
 
+  // Tangible operations
+  addTangible: (tangible: TangibleConfig) =>
+    set((state) => ({
+      tangibles: [...state.tangibles, tangible],
+    })),
+
+  updateTangible: (id: string, updates: Partial<Omit<TangibleConfig, 'id'>>) =>
+    set((state) => ({
+      tangibles: state.tangibles.map((tangible) =>
+        tangible.id === id ? { ...tangible, ...updates } : tangible
+      ),
+    })),
+
+  deleteTangible: (id: string) =>
+    set((state) => ({
+      tangibles: state.tangibles.filter((tangible) => tangible.id !== id),
+    })),
+
+  setTangibles: (tangibles: TangibleConfig[]) =>
+    set({
+      tangibles,
+    }),
+
   // Group operations
   addGroup: (group: Group) =>
     set((state) => ({
@@ -558,6 +597,7 @@ export const useGraphStore = create<GraphStore & GraphActions>((set) => ({
       nodeTypes: data.nodeTypes,
       edgeTypes: data.edgeTypes,
       labels: data.labels || [],
+      tangibles: data.tangibles || [],
     });
   },
 }));

src/stores/persistence/types.ts

@@ -1,4 +1,4 @@
-import type { ActorData, RelationData, GroupData, NodeTypeConfig, EdgeTypeConfig, LabelConfig } from '../../types';
+import type { ActorData, RelationData, GroupData, NodeTypeConfig, EdgeTypeConfig, LabelConfig, TangibleConfig } from '../../types';
 import type { ConstellationState } from '../../types/timeline';
 import type { Bibliography } from '../../types/bibliography';
 
@@ -59,6 +59,8 @@ export interface ConstellationDocument {
   labels?: LabelConfig[];
   // Global bibliography for the entire document (optional for backward compatibility)
   bibliography?: Bibliography;
+  // Global tangibles for the entire document (optional for backward compatibility)
+  tangibles?: TangibleConfig[];
   // Timeline with multiple states - every document has this
   // The graph is stored within each state (nodes and edges only, not types)
   timeline: {

src/stores/timelineStore.ts

@@ -308,6 +308,7 @@ export const useTimelineStore = create<TimelineStore & TimelineActions>(
         nodeTypes: graphStore.nodeTypes,
         edgeTypes: graphStore.edgeTypes,
         labels: graphStore.labels,
+        tangibles: graphStore.tangibles,
       });
     },
 
@@ -407,6 +408,33 @@ export const useTimelineStore = create<TimelineStore & TimelineActions>(
       // Push to history BEFORE making changes
       pushDocumentHistory(activeDocumentId, `Delete State: ${stateName}`);
 
+      // Delete tangibles that reference this state
+      const workspaceStore = useWorkspaceStore.getState();
+      const doc = workspaceStore.documents.get(activeDocumentId);
+      if (doc && doc.tangibles) {
+        const tangiblesBefore = doc.tangibles.length;
+        doc.tangibles = doc.tangibles.filter(
+          (tangible) =>
+            !(
+              (tangible.mode === 'state' || tangible.mode === 'stateDial') &&
+              tangible.stateId === stateId
+            )
+        );
+        const tangiblesDeleted = tangiblesBefore - doc.tangibles.length;
+
+        if (tangiblesDeleted > 0) {
+          // Sync to graphStore if active
+          if (activeDocumentId === workspaceStore.activeDocumentId) {
+            useGraphStore.getState().setTangibles(doc.tangibles);
+          }
+
+          useToastStore.getState().showToast(
+            `Deleted ${tangiblesDeleted} tangible(s) referencing this state`,
+            'info'
+          );
+        }
+      }
+
       set((state) => {
         const newTimelines = new Map(state.timelines);
         const timeline = newTimelines.get(activeDocumentId)!;

src/stores/workspace/types.ts

@@ -1,5 +1,5 @@
 import type { ConstellationDocument } from '../persistence/types';
-import type { NodeTypeConfig, EdgeTypeConfig, LabelConfig } from '../../types';
+import type { NodeTypeConfig, EdgeTypeConfig, LabelConfig, TangibleConfig } from '../../types';
 
 /**
  * Workspace Types
@@ -101,6 +101,11 @@ export interface WorkspaceActions {
   updateLabelInDocument: (documentId: string, labelId: string, updates: Partial<Omit<LabelConfig, 'id'>>) => void;
   deleteLabelFromDocument: (documentId: string, labelId: string) => void;
 
+  // Tangible management (document-level)
+  addTangibleToDocument: (documentId: string, tangible: TangibleConfig) => void;
+  updateTangibleInDocument: (documentId: string, tangibleId: string, updates: Partial<Omit<TangibleConfig, 'id'>>) => void;
+  deleteTangibleFromDocument: (documentId: string, tangibleId: string) => void;
+
   // Viewport operations
   saveViewport: (documentId: string, viewport: { x: number; y: number; zoom: number }) => void;
   getViewport: (documentId: string) => { x: number; y: number; zoom: number } | undefined;

src/stores/workspace/useActiveDocument.ts

@@ -2,7 +2,7 @@ import { useEffect, useRef } from 'react';
 import { useWorkspaceStore } from '../workspaceStore';
 import { useGraphStore } from '../graphStore';
 import { useTimelineStore } from '../timelineStore';
-import type { Actor, Relation, Group, NodeTypeConfig, EdgeTypeConfig, LabelConfig } from '../../types';
+import type { Actor, Relation, Group, NodeTypeConfig, EdgeTypeConfig, LabelConfig, TangibleConfig } from '../../types';
 import { getCurrentGraphFromDocument } from './documentUtils';
 
 /**
@@ -31,12 +31,14 @@ export function useActiveDocument() {
   const setNodeTypes = useGraphStore((state) => state.setNodeTypes);
   const setEdgeTypes = useGraphStore((state) => state.setEdgeTypes);
   const setLabels = useGraphStore((state) => state.setLabels);
+  const setTangibles = useGraphStore((state) => state.setTangibles);
   const graphNodes = useGraphStore((state) => state.nodes);
   const graphEdges = useGraphStore((state) => state.edges);
   const graphGroups = useGraphStore((state) => state.groups);
   const graphNodeTypes = useGraphStore((state) => state.nodeTypes);
   const graphEdgeTypes = useGraphStore((state) => state.edgeTypes);
   const graphLabels = useGraphStore((state) => state.labels);
+  const graphTangibles = useGraphStore((state) => state.tangibles);
 
   // Track unload timers for inactive documents
   const unloadTimersRef = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map());
@@ -54,6 +56,7 @@ export function useActiveDocument() {
     nodeTypes: NodeTypeConfig[];
     edgeTypes: EdgeTypeConfig[];
     labels: LabelConfig[];
+    tangibles: TangibleConfig[];
   }>({
     documentId: null,
     nodes: [],
@@ -62,6 +65,7 @@ export function useActiveDocument() {
     nodeTypes: [],
     edgeTypes: [],
     labels: [],
+    tangibles: [],
   });
 
   /**
@@ -99,6 +103,7 @@ export function useActiveDocument() {
       setNodeTypes(currentGraph.nodeTypes as never[]);
       setEdgeTypes(currentGraph.edgeTypes as never[]);
       setLabels(activeDocument.labels || []);
+      setTangibles(activeDocument.tangibles || []);
 
       // Update the last synced state to match what we just loaded
       lastSyncedStateRef.current = {
@@ -109,6 +114,7 @@ export function useActiveDocument() {
         nodeTypes: currentGraph.nodeTypes as NodeTypeConfig[],
         edgeTypes: currentGraph.edgeTypes as EdgeTypeConfig[],
         labels: activeDocument.labels || [],
+        tangibles: activeDocument.tangibles || [],
       };
 
       // Clear loading flag after a brief delay to allow state to settle
@@ -127,6 +133,7 @@ export function useActiveDocument() {
       setEdges([]);
       setGroups([]);
       setLabels([]);
+      setTangibles([]);
       // Note: We keep nodeTypes and edgeTypes so they're available for new documents
 
       // Clear the last synced state
@@ -138,6 +145,7 @@ export function useActiveDocument() {
         nodeTypes: [],
         edgeTypes: [],
         labels: [],
+        tangibles: [],
       };
 
       // Clear loading flag after a brief delay
@@ -145,7 +153,7 @@ export function useActiveDocument() {
         isLoadingRef.current = false;
       }, 100);
     }
-  }, [activeDocumentId, activeDocument, documents, setNodes, setEdges, setGroups, setNodeTypes, setEdgeTypes, setLabels]);
+  }, [activeDocumentId, activeDocument, documents, setNodes, setEdges, setGroups, setNodeTypes, setEdgeTypes, setLabels, setTangibles]);
 
   // Save graphStore changes back to workspace (debounced via workspace)
   useEffect(() => {
@@ -183,7 +191,7 @@ export function useActiveDocument() {
       console.log(`Document ${activeDocumentId} has changes, marking as dirty`);
       markDocumentDirty(activeDocumentId);
 
-      // Update the last synced state (keep types and labels for reference, but don't track them for changes)
+      // Update the last synced state (keep types, labels, tangibles for reference, but don't track them for changes)
       lastSyncedStateRef.current = {
         documentId: activeDocumentId,
         nodes: graphNodes as Actor[],
@@ -192,6 +200,7 @@ export function useActiveDocument() {
         nodeTypes: graphNodeTypes as NodeTypeConfig[],
         edgeTypes: graphEdgeTypes as EdgeTypeConfig[],
         labels: graphLabels as LabelConfig[],
+        tangibles: graphTangibles as TangibleConfig[],
       };
 
       /**
@@ -220,7 +229,7 @@ export function useActiveDocument() {
 
       return () => clearTimeout(timeoutId);
     }
-  }, [graphNodes, graphEdges, graphGroups, graphNodeTypes, graphEdgeTypes, graphLabels, activeDocumentId, activeDocument, documents, markDocumentDirty, saveDocument]);
+  }, [graphNodes, graphEdges, graphGroups, graphNodeTypes, graphEdgeTypes, graphLabels, graphTangibles, activeDocumentId, activeDocument, documents, markDocumentDirty, saveDocument]);
 
   // Memory management: Unload inactive documents after timeout
   useEffect(() => {

src/stores/workspaceStore.test.ts

@@ -6,6 +6,7 @@ import {
   clearWorkspaceStorage,
 } from './workspace/persistence';
 import { mockNodeTypes, mockEdgeTypes } from '../test-utils/mocks';
+import type { TangibleConfig } from '../types';
 
 // Create a mock showToast that we can track
 const mockShowToast = vi.fn();
@@ -38,9 +39,11 @@ vi.mock('./graphStore', () => ({
       nodeTypes: [],
       edgeTypes: [],
       labels: [],
+      tangibles: [],
       setNodeTypes: vi.fn(),
       setEdgeTypes: vi.fn(),
       setLabels: vi.fn(),
+      setTangibles: vi.fn(),
       loadGraphState: vi.fn(),
     }),
     setState: vi.fn(),
@@ -634,6 +637,124 @@ describe('workspaceStore', () => {
     });
   });
 
+  describe('Tangible Management', () => {
+    let documentId: string;
+
+    beforeEach(() => {
+      documentId = useWorkspaceStore.getState().createDocument('Test Doc');
+    });
+
+    describe('addTangibleToDocument', () => {
+      it('should add tangible to document', () => {
+        const { addTangibleToDocument } = useWorkspaceStore.getState();
+
+        const tangible = {
+          name: 'Red Block',
+          mode: 'filter' as const,
+          filterLabels: ['label-1'],
+          hardwareId: 'token-001',
+        };
+
+        addTangibleToDocument(documentId, tangible as TangibleConfig);
+
+        const doc = useWorkspaceStore.getState().documents.get(documentId);
+        expect(doc?.tangibles).toHaveLength(1);
+        expect(doc?.tangibles?.[0].id).toMatch(/^tangible_\d+_[a-z0-9]+$/); // Random ID format
+        expect(doc?.tangibles?.[0].name).toBe('Red Block');
+        expect(doc?.tangibles?.[0].hardwareId).toBe('token-001');
+      });
+
+      it('should allow duplicate tangible names', () => {
+        const { addTangibleToDocument } = useWorkspaceStore.getState();
+
+        const tangible = {
+          name: 'Red Block',
+          mode: 'filter' as const,
+          filterLabels: ['label-1'],
+        };
+
+        addTangibleToDocument(documentId, tangible as TangibleConfig);
+        addTangibleToDocument(documentId, tangible as TangibleConfig); // Same name is allowed (IDs are unique)
+
+        const doc = useWorkspaceStore.getState().documents.get(documentId);
+        expect(doc?.tangibles).toHaveLength(2); // Both added
+        expect(doc?.tangibles?.[0].id).not.toBe(doc?.tangibles?.[1].id); // Different IDs
+      });
+
+
+      it('should handle invalid document ID', () => {
+        const { addTangibleToDocument } = useWorkspaceStore.getState();
+
+        const tangible = {
+          name: 'Red Block',
+          mode: 'filter' as const,
+          filterLabels: [],
+        };
+
+        // Should not throw
+        expect(() => addTangibleToDocument('invalid-id', tangible as TangibleConfig)).not.toThrow();
+      });
+    });
+
+    describe('updateTangibleInDocument', () => {
+      beforeEach(() => {
+        const { addTangibleToDocument } = useWorkspaceStore.getState();
+        addTangibleToDocument(documentId, {
+          name: 'Original',
+          mode: 'filter' as const,
+          filterLabels: ['label-1'],
+        } as TangibleConfig);
+      });
+
+      it('should update tangible in document', () => {
+        const { updateTangibleInDocument } = useWorkspaceStore.getState();
+
+        // Get the auto-generated ID
+        const doc = useWorkspaceStore.getState().documents.get(documentId);
+        const tangibleId = doc?.tangibles?.[0].id!;
+
+        updateTangibleInDocument(documentId, tangibleId, { name: 'Updated', hardwareId: 'token-002' });
+
+        const updatedDoc = useWorkspaceStore.getState().documents.get(documentId);
+        expect(updatedDoc?.tangibles?.[0].name).toBe('Updated');
+        expect(updatedDoc?.tangibles?.[0].hardwareId).toBe('token-002');
+      });
+    });
+
+    describe('deleteTangibleFromDocument', () => {
+      beforeEach(() => {
+        const { addTangibleToDocument } = useWorkspaceStore.getState();
+        addTangibleToDocument(documentId, {
+          name: 'T1',
+          mode: 'filter' as const,
+          filterLabels: ['label-1'],
+        } as TangibleConfig);
+        addTangibleToDocument(documentId, {
+          name: 'T2',
+          mode: 'state' as const,
+          stateId: 's1',
+        } as TangibleConfig);
+      });
+
+      it('should delete tangible from document', () => {
+        const { deleteTangibleFromDocument } = useWorkspaceStore.getState();
+
+        // Get the first tangible's ID
+        const doc = useWorkspaceStore.getState().documents.get(documentId);
+        const firstTangibleId = doc?.tangibles?.[0].id!;
+        const secondTangibleId = doc?.tangibles?.[1].id!;
+
+        deleteTangibleFromDocument(documentId, firstTangibleId);
+
+        const updatedDoc = useWorkspaceStore.getState().documents.get(documentId);
+        expect(updatedDoc?.tangibles).toHaveLength(1);
+        expect(updatedDoc?.tangibles?.[0].id).toBe(secondTangibleId);
+        expect(updatedDoc?.tangibles?.[0].name).toBe('T2');
+      });
+
+    });
+  });
+
   describe('Edge Cases', () => {
     it('should handle rapid document creation', () => {
       const { createDocument } = useWorkspaceStore.getState();

src/stores/workspaceStore.ts

@@ -1402,6 +1402,7 @@ export const useWorkspaceStore = create<Workspace & WorkspaceActions>((set, get)
 
     // Capture original state for rollback
     const originalLabels = [...doc.labels];
+    const originalTangibles = doc.tangibles ? [...doc.tangibles] : [];
     const originalIsDirty = state.documentMetadata.get(documentId)?.isDirty;
 
     // Capture original timeline for rollback (shallow copy of the entire timeline)
@@ -1414,7 +1415,20 @@ export const useWorkspaceStore = create<Workspace & WorkspaceActions>((set, get)
         // 1. Remove from document's labels
         doc.labels = (doc.labels || []).filter((label) => label.id !== labelId);
 
-        // 2. Remove label from all nodes and edges in all timeline states (IMMUTABLE)
+        // 2. Remove label from tangible filterLabels arrays
+        if (doc.tangibles) {
+          doc.tangibles = doc.tangibles.map((tangible) => {
+            if (tangible.mode === 'filter' && tangible.filterLabels) {
+              return {
+                ...tangible,
+                filterLabels: tangible.filterLabels.filter((id) => id !== labelId),
+              };
+            }
+            return tangible;
+          });
+        }
+
+        // 3. Remove label from all nodes and edges in all timeline states (IMMUTABLE)
         if (timeline) {
           // ✅ Build new states Map with cleaned labels (immutable update)
           const newStates = new Map();
@@ -1480,20 +1494,22 @@ export const useWorkspaceStore = create<Workspace & WorkspaceActions>((set, get)
           }
         }
 
-        // 3. Save document to storage (can throw QuotaExceededError)
+        // 4. Save document to storage (can throw QuotaExceededError)
         saveDocumentToStorage(documentId, doc);
 
-        // 4. Mark as dirty
+        // 5. Mark as dirty
         get().markDocumentDirty(documentId);
 
-        // 5. If this is the active document, sync to graphStore
+        // 6. If this is the active document, sync to graphStore
         if (documentId === state.activeDocumentId) {
           useGraphStore.getState().setLabels(doc.labels);
+          useGraphStore.getState().setTangibles(doc.tangibles || []);
         }
       },
       () => {
         // Rollback on failure
         doc.labels = originalLabels;
+        doc.tangibles = originalTangibles;
 
         // Restore entire timeline (atomic rollback)
         if (originalTimeline) {
@@ -1517,12 +1533,183 @@ export const useWorkspaceStore = create<Workspace & WorkspaceActions>((set, get)
           metadata.isDirty = originalIsDirty;
         }
 
-        // Sync labels to graphStore if active
+        // Sync labels and tangibles to graphStore if active
         if (documentId === state.activeDocumentId) {
           useGraphStore.getState().setLabels(doc.labels);
+          useGraphStore.getState().setTangibles(doc.tangibles || []);
         }
       },
       'delete label'
     );
   },
+
+  // ===========================
+  // Tangible Management
+  // ===========================
+
+  addTangibleToDocument: (documentId: string, tangible) => {
+    const state = get();
+    const doc = state.documents.get(documentId);
+
+    if (!doc) {
+      console.error(`Document ${documentId} not found`);
+      return;
+    }
+
+    // Initialize tangibles array if it doesn't exist (backward compatibility)
+    if (!doc.tangibles) {
+      doc.tangibles = [];
+    }
+
+    // Auto-generate internal ID with random value (like nodes/documents/states)
+    const id = `tangible_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+
+    // Validate unique hardware ID (if provided)
+    if (tangible.hardwareId && doc.tangibles.some((t) => t.hardwareId === tangible.hardwareId)) {
+      useToastStore.getState().showToast('This hardware ID is already assigned to another tangible', 'error');
+      return;
+    }
+
+    // Validate mode-specific fields
+    if (tangible.mode === 'filter' && (!tangible.filterLabels || tangible.filterLabels.length === 0)) {
+      useToastStore.getState().showToast('Filter mode requires at least one label', 'error');
+      return;
+    }
+    if ((tangible.mode === 'state' || tangible.mode === 'stateDial') && !tangible.stateId) {
+      useToastStore.getState().showToast('State mode requires a state selection', 'error');
+      return;
+    }
+
+    // Create tangible with auto-generated ID
+    const newTangible = { ...tangible, id };
+
+    // Capture original state for rollback
+    const originalTangibles = [...doc.tangibles];
+    const originalIsDirty = state.documentMetadata.get(documentId)?.isDirty;
+
+    get().executeTypeTransaction(
+      () => {
+        doc.tangibles = [...(doc.tangibles || []), newTangible];
+        saveDocumentToStorage(documentId, doc);
+        get().markDocumentDirty(documentId);
+        if (documentId === state.activeDocumentId) {
+          useGraphStore.getState().setTangibles(doc.tangibles);
+        }
+      },
+      () => {
+        doc.tangibles = originalTangibles;
+        const metadata = state.documentMetadata.get(documentId);
+        if (metadata && originalIsDirty !== undefined) {
+          metadata.isDirty = originalIsDirty;
+        }
+        if (documentId === state.activeDocumentId) {
+          useGraphStore.getState().setTangibles(doc.tangibles);
+        }
+      },
+      'add tangible'
+    );
+  },
+
+  updateTangibleInDocument: (documentId: string, tangibleId: string, updates) => {
+    const state = get();
+    const doc = state.documents.get(documentId);
+
+    if (!doc) {
+      console.error(`Document ${documentId} not found`);
+      return;
+    }
+
+    // Initialize tangibles array if it doesn't exist (backward compatibility)
+    if (!doc.tangibles) {
+      doc.tangibles = [];
+    }
+
+    // Validate unique hardware ID if being updated
+    if (updates.hardwareId !== undefined && updates.hardwareId) {
+      const existingWithHardwareId = doc.tangibles.find((t) => t.hardwareId === updates.hardwareId && t.id !== tangibleId);
+      if (existingWithHardwareId) {
+        useToastStore.getState().showToast('This hardware ID is already assigned to another tangible', 'error');
+        return;
+      }
+    }
+
+    // Validate mode-specific fields if mode is being updated
+    if (updates.mode === 'filter' && (!updates.filterLabels || updates.filterLabels.length === 0)) {
+      useToastStore.getState().showToast('Filter mode requires at least one label', 'error');
+      return;
+    }
+    if ((updates.mode === 'state' || updates.mode === 'stateDial') && !updates.stateId) {
+      useToastStore.getState().showToast('State mode requires a state selection', 'error');
+      return;
+    }
+
+    // Capture original state for rollback
+    const originalTangibles = [...doc.tangibles];
+    const originalIsDirty = state.documentMetadata.get(documentId)?.isDirty;
+
+    get().executeTypeTransaction(
+      () => {
+        doc.tangibles = (doc.tangibles || []).map((tangible) =>
+          tangible.id === tangibleId ? { ...tangible, ...updates } : tangible
+        );
+        saveDocumentToStorage(documentId, doc);
+        get().markDocumentDirty(documentId);
+        if (documentId === state.activeDocumentId) {
+          useGraphStore.getState().setTangibles(doc.tangibles);
+        }
+      },
+      () => {
+        doc.tangibles = originalTangibles;
+        const metadata = state.documentMetadata.get(documentId);
+        if (metadata && originalIsDirty !== undefined) {
+          metadata.isDirty = originalIsDirty;
+        }
+        if (documentId === state.activeDocumentId) {
+          useGraphStore.getState().setTangibles(doc.tangibles);
+        }
+      },
+      'update tangible'
+    );
+  },
+
+  deleteTangibleFromDocument: (documentId: string, tangibleId: string) => {
+    const state = get();
+    const doc = state.documents.get(documentId);
+
+    if (!doc) {
+      console.error(`Document ${documentId} not found`);
+      return;
+    }
+
+    // Initialize tangibles array if it doesn't exist (backward compatibility)
+    if (!doc.tangibles) {
+      doc.tangibles = [];
+    }
+
+    // Capture original state for rollback
+    const originalTangibles = [...doc.tangibles];
+    const originalIsDirty = state.documentMetadata.get(documentId)?.isDirty;
+
+    get().executeTypeTransaction(
+      () => {
+        doc.tangibles = (doc.tangibles || []).filter((tangible) => tangible.id !== tangibleId);
+        saveDocumentToStorage(documentId, doc);
+        get().markDocumentDirty(documentId);
+        if (documentId === state.activeDocumentId) {
+          useGraphStore.getState().setTangibles(doc.tangibles);
+        }
+      },
+      () => {
+        doc.tangibles = originalTangibles;
+        const metadata = state.documentMetadata.get(documentId);
+        if (metadata && originalIsDirty !== undefined) {
+          metadata.isDirty = originalIsDirty;
+        }
+        if (documentId === state.activeDocumentId) {
+          useGraphStore.getState().setTangibles(doc.tangibles);
+        }
+      },
+      'delete tangible'
+    );
+  },
 }));

src/types/index.ts

@@ -66,6 +66,19 @@ export interface LabelConfig {
   description?: string;
 }
 
+// Tangible Configuration
+export type TangibleMode = 'filter' | 'state' | 'stateDial';
+
+export interface TangibleConfig {
+  id: string;                   // Internal unique identifier (auto-generated from name)
+  name: string;
+  mode: TangibleMode;
+  description?: string;
+  hardwareId?: string;          // Hardware token/device ID (editable, must be unique if present)
+  filterLabels?: string[];      // For filter mode: array of LabelConfig IDs
+  stateId?: string;             // For state/stateDial mode: ConstellationState ID
+}
+
 // Group Types
 export interface GroupData extends Record<string, unknown> {
   label: string;
@@ -86,6 +99,7 @@ export interface GraphState {
   nodeTypes: NodeTypeConfig[];
   edgeTypes: EdgeTypeConfig[];
   labels: LabelConfig[];
+  tangibles: TangibleConfig[];
 }
 
 // Editor Settings
@@ -114,6 +128,10 @@ export interface GraphActions {
   addLabel: (label: LabelConfig) => void;
   updateLabel: (id: string, updates: Partial<Omit<LabelConfig, 'id'>>) => void;
   deleteLabel: (id: string) => void;
+  addTangible: (tangible: TangibleConfig) => void;
+  updateTangible: (id: string, updates: Partial<Omit<TangibleConfig, 'id'>>) => void;
+  deleteTangible: (id: string) => void;
+  setTangibles: (tangibles: TangibleConfig[]) => void;
   addGroup: (group: Group) => void;
   updateGroup: (id: string, updates: Partial<GroupData>) => void;
   deleteGroup: (id: string, ungroupActors?: boolean) => void;
@@ -129,7 +147,7 @@ export interface GraphActions {
   setLabels: (labels: LabelConfig[]) => void;
   // NOTE: exportToFile and importFromFile have been removed
   // Import/export is now handled by the workspace-level system (workspaceStore)
-  loadGraphState: (data: { nodes: Actor[]; edges: Relation[]; groups?: Group[]; nodeTypes: NodeTypeConfig[]; edgeTypes: EdgeTypeConfig[]; labels?: LabelConfig[] }) => void;
+  loadGraphState: (data: { nodes: Actor[]; edges: Relation[]; groups?: Group[]; nodeTypes: NodeTypeConfig[]; edgeTypes: EdgeTypeConfig[]; labels?: LabelConfig[]; tangibles?: TangibleConfig[] }) => void;
 }
 
 export interface EditorActions {